Professional Documents
Culture Documents
OCI User Guide PDF
OCI User Guide PDF
7/8/2020
Copyright © 2016, 2020, Oracle and/or its affiliates. All rights reserved.
This software and related documentation are provided under a license agreement containing
restrictions on use and disclosure and are protected by intellectual property laws. Except as
expressly permitted in your license agreement or allowed by law, you may not use, copy,
reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform,
publish, or display any part, in any form, or by any means. Reverse engineering,
disassembly, or decompilation of this software, unless required by law for interoperability, is
prohibited.
The information contained herein is subject to change without notice and is not warranted to
be error-free. If you find any errors, please report them to us in writing.
U.S. GOVERNMENT END USERS: Oracle programs, including any operating system,
integrated software, any programs installed on the hardware, and/or documentation,
delivered to U.S. Government end users are "commercial computer software" pursuant to the
applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As
such, use, duplication, disclosure, modification, and adaptation of the programs, including any
operating system, integrated software, any programs installed on the hardware, and/or
documentation, shall be subject to license terms and license restrictions applicable to the
programs. No other rights are granted to the U.S. Government.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may
be trademarks of their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC
trademarks are used under license and are trademarks or registered trademarks of SPARC
International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or
registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The
Open Group.
This software or hardware and documentation may provide access to or information about
content, products, and services from third parties. Oracle Corporation and its affiliates are not
responsible for and expressly disclaim all warranties of any kind with respect to third-party
content, products, and services unless otherwise set forth in an applicable agreement
between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any
loss, costs, or damages incurred due to your access to or use of third-party content, products,
or services, except as set forth in an applicable agreement between you and Oracle.
For information about Oracle's commitment to accessibility, visit the Oracle Accessibility
Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.
Oracle customers that have purchased support have access to electronic support through My
Oracle Support. For information, visit
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.
CONTENTS
Supported Images (Including Custom Images) and Shapes for Worker Nodes 1177
Supported Admission Controllers 1180
Kubernetes Versions and Container Engine for Kubernetes 1184
Supported Versions of Kubernetes 1185
Upgrading Clusters to Newer Kubernetes Versions 1188
'Upgrading' the Image Running on Worker Nodes by Creating a New Node Pool 1195
Configuring DNS Servers for Kubernetes Clusters 1196
Creating Load Balancers to Distribute Traffic Between Cluster Nodes 1198
Creating a Persistent Volume Claim 1208
Adding OCI Service Broker for Kubernetes to Clusters 1213
Example: Setting Up an Ingress Controller on a Cluster 1215
Example: Installing Calico and Setting Up Network Policies 1225
Container Engine for Kubernetes Metrics 1229
GLOSSARY 6112
RELEASE NOTES 6137
If you're new to Oracle Cloud Infrastructure and would like to learn some key concepts and
take a quick tutorial, see the Oracle Cloud Infrastructure Getting Started Guide.
If you're ready to create cloud resources such as users, access controls, cloud networks,
instances, and storage volumes, this guide is right for you. It provides the following
information about using Oracle Cloud Infrastructure:
Container Engine for Defining and creating Kubernetes Container Engine for
Kubernetes clusters to enable the deployment, Kubernetes
scaling, and management of
containerized applications.
Data Catalog Find, govern, and track Oracle Cloud See the online
data assets. documentation: Data
Catalog.
Data Flow Creating, managing, and running Spark See the online
applications in a serverless documentation: Data
environment. Flow.
Data Integration Design data flows using a visually rich See the online
interface to extract, transform, and load documentation: Data
data from data sources to targets. Integration.
Data Science Build, train, deploy, and manage See the online
machine learning models on Oracle documentation: Data
Cloud. Science Overview.
NoSQL Database Provisioning for JSON, Table, and Key- See the online
Cloud Value datatypes using on-demand documentation:
throughput and a storage basis. NoSQL Database
For a description of the terminology used throughout this guide, see the GLOSSARY.
Need API Documentation?
For general information, see REST APIs. For links to the detailed service API documentation,
see the online help at https://docs.cloud.oracle.com/iaas/Content/home.htm.
Free Trial
The Free Trial provides you with $300 of cloud credits that are valid for up to 30 days. You
may spend these credits on any eligible Oracle Cloud Infrastructure service.
Getting Started
Start for Free
For more information, and to see a complete list of services available to you during the trial,
visit the Free Trial website.
Note
For security purposes, most users will need a mobile phone number and a credit card to
create an account. Your credit card will not be charged unless you upgrade your account.
Paid resources that were provisioned with your credits during your free trial are reclaimed by
Oracle unless you upgrade your account.
Pay as You Go accounts are available with no commitment, or contact an Oracle sales
representative in your location to learn about monthly and annual flex accounts that offers
discounted pricing. For more information, see Oracle Cloud Infrastructure Pricing.
Using the Always Free resources, you can provision a virtual machine (VM) instance, an
Oracle Autonomous Database, and the networking, load balancing, and storage resources
needed to support the applications that you want build. With these resources, you can do
things like run small-scale applications or perform proof-of-concept testing.
The following list summarizes the Oracle Cloud Always Free-eligible resources that you can
provision in your tenancy:
For detailed information about the Always Free resources, see Details of the Always Free
Resources.
You can find your tenancy’s limits for Always Free resources in the Console. To check these
limits: Open the navigation menu. Under Governance and Administration, go to Limits,
Quotas and Usage.
Tip
3. Click the Create Stack button to open the Create Stack dialog.
4. In the Create Stack dialog, click Sample Solution.
5. Click Select Solution to browse available solutions.
6. Select the checkbox for Sample E-Commerce Application.
7. Click Select Solution.
8. Optionally, provide a name for the new stack. If you don't provide a name, a default
name is provided on the server.
9. Optionally, provide a description for the stack.
10. Optionally, select a different compartment from your current compartment in which to
create the stack. To do so, select a compartment from the Create In Compartment
drop-down.
11. Click Next to proceed to the Configure Variables panel.
12. The variables displayed in the Configure Variables panel are auto-populated from the
Terraform file that you uploaded. You don't need to change these variables if you are
provisioning your Always Free resources using the Terraform file provided by Oracle.
13. Click Next to proceed to the Review panel.
14. Verify your stack configuration, then click Create to create your stack.
Your set of Always Free resources should take no more than a few minutes to provision.
Additional Information
See Frequently Asked Questions: Oracle Cloud Infrastructure Free Tier for answers to your
questions about Free Tier accounts and resources.
Compute
All tenancies get two Always Free Compute virtual machine (VM) instances.
You must create the Always Free Compute instances in your home region.
Tip
See Oracle-Provided Images for more information about the available operating systems. For
steps to create an Always Free-eligible Compute instance, see "Tutorial - Launching Your First
Linux Instance" in the Oracle Cloud Infrastructure Getting Started Guide.
Database
All tenancies get two Always Free Oracle Autonomous Databases. The Autonomous Databases
use shared Exadata infrastructure (meaning Oracle handles the database infrastructure
provisioning and maintenance). For current regional availability, see the "Always Free Cloud
Services" section of Data Regions for Platform and Infrastructure Services.
Tip
Note
See Overview of the Always Free Autonomous Database for additional product details. See To
create an Always Free Autonomous Database for steps to create an Always Free Autonomous
Database.
Load Balancing
All tenancies get one Always Free 10 Mbps load balancer.
For information about provisioning an Always Free load balancer, see Getting Started with
Load Balancing.
Block Volume
All tenancies receive a total of 100 GB of Always Free Block Volume storage, and five volume
backups. These amounts apply to both boot volumes and block volumes combined. When you
provision a Compute instance, the instance automatically receives a 50 GB boot volume for
storage. You can also create and attach block volumes to expand the storage capacity of a
Compute instance. For more information, see Creating a Volume and Attaching a Volume.
When you create a Compute instance, the default boot volume size for the instance is 50 GB,
which counts towards your allotment of 100 GB. You can customize the instance's boot volume
size up to 100 GB; however, this will use up your full allotment of storage for Always Free
Block Volume resources. Also, because the minimum boot volume size allowed for Compute
instances is 50 GB, launching two instances will use all your Always Free Block Volume
resources. Alternatively, you can launch one instance with the default boot volume size of 50
GB, and then create and attach a 50 GB block volume to expand the storage capacity of the
instance. For more information, see Creating a Volume and Attaching a Volume. Although it is
possible to mix paid and Always Free resources, Oracle does not recommend this. If you have
used up your allotment of Always Free Block Volume resources, you can free up block storage
resources by terminating an Always Free instance and deleting the boot volume, or
terminating an Always Free block volume.
You can have a maximum of five Always Free volume backups at any time. This applies to
both boot volume and block volume backups. For example, you could have three boot volume
backups for your Always Free instance and two block volume backups for your Always Free
block volumes. In this example, if you try to create new backups, the operation will fail with
an error until you delete existing Always Free volume backups. For more information about
volume backups, see Overview of Block Volume Backups and Overview of Boot Volume
Backups.
Object Storage
All tenancies get a total of 20 GiB (gibibytes) of Always Free Object Storage.
If you have a paid account, Always Free Object Storage includes the following:
Important
See Putting Data into Object Storage for instructions on using your Always Free Object
Storage resources.
Vault
All tenancies receive a total of 20 key versions and 150 Always Free Vault secrets. You can
spread these keys or secrets across any number of vaults in the tenancy, although virtual
private vaults are not included in the Always Free resources. Each secret can have up to 40
total secret versions.
If you have used up your allotment of Always Free secrets, you can release resources by
scheduling a secret or secret version for deletion. At minimum, you do have to wait a day
before the secret or secret version is deleted.
I just signed up and I cannot access specific services. What can I do?
Registering your account with all services and regions can take a few minutes. Check again
after a few minutes have passed.
What happens when my Free Trial expires or my credits are used up?
When you've reached the end of your 30 day trial, or used all of your Free Trial credits
(whichever comes first), you will no longer be able to create new paid resources. However,
your account will remain active. Your existing resources will continue to run for a few days,
allowing you to upgrade your account and keep your resources before they're reclaimed by
Oracle. (Note that reclaimed resources cannot be recovered—they are permanently deleted.)
Resources identified as Always Free will not be reclaimed. After your Free Trial expires, you'll
continue to be able to use and manage your existing Always Free resources, and create new
Always Free resources according to tenancy limits.
If you see this message, your resources have been reclaimed and cannot be restored.
If you don't see an Upgrade link on the Console page you are viewing, you can click the
Oracle Cloud logo at the top of the Console and then look for the Upgrade link in the sidebar
on the right side of the page.
Shared Responsibilities
Oracle Cloud Infrastructure for government offers best-in-class security technology and
operational processes to secure its enterprise cloud services. However, for you to securely
run your workloads , you must be aware of your security and compliance responsibilities. By
design, Oracle provides security of cloud infrastructure and operations (cloud operator access
controls, infrastructure security patching, and so on), and you are responsible for securely
configuring your cloud resources. Security in the cloud is a shared responsibility between you
and Oracle.
For more information about shared responsibilities in the Oracle Cloud, see the following
white papers:
As a Government Cloud customer, you must bring your own identity provider that meets your
agency's compliance requirements and supports common access card/personal identity
verification card (CAC/PIV) authentication. You can federate Oracle Cloud Infrastructure with
SAML 2.0 compliant identity providers that also support CAC/PIV authentication. For
instructions on setting up a federation, see Federating with Identity Providers.
REMOVE THE ORACLE CLOUD I NFRASTRUCTURE DEFAULT ADMINISTRATOR USER AND ANY OTHER NON-
FEDERATED USERS
When your organization signs up for an Oracle account and Identity Domain, Oracle sets up a
default administrator for the account. This person will be the first IAM user for your company
and will have full administrator access to your tenancy. This user can set up your federation.
After you have successfully set up the federation with your chosen identity provider, you can
delete the default administrator user and any other IAM service local users you might have
added to assist with setting up your tenancy. Deleting the local, non-federated users ensures
that only users in your chosen identity provider can access Oracle Cloud Infrastructure.
More details
a. Open a supported browser and go to the Government Cloud Console URL.
b. Enter your Cloud Tenant and click Continue.
c. On the Single Sign-On pane, select your identity provider and click Continue.
After you set up CAC/PIV authentication with your identity provider and successfully federate
with Oracle Cloud Infrastructure, you can use your CAC/PIV credentials to sign in to the Oracle
Cloud Infrastructure Console. See your identity provider's documentation for the specific
details for your implementation.
US Government Cloud customers have the option to enable IPv6 addressing for their VCNs.
For more information, see IPv6 Addresses.
You can set up CAC/PIV authentication using third-party tools to enable multi-factor
authentication for securely connecting to your compute hosts. Example tools include PuTTY-
CAC for Windows and Open SC for macOS. For more information see the U.S. Government
website, PIV Usage Guidelines.
Government Cloud customers are responsible for enabling FIPS mode for the operating
systems on their Compute hosts. To make your operating system compliant with Federal
Information Processing Standard (FIPS) Publication 140-2, follow the guidelines for your
operating system:
ORACLE LINUX
UBUNTU
Follow the guidance provided at Data Encryption for Web console and Reporting server
Connections.
First, follow the guidance provided at How to Use FIPS Compliant Algorithms.
Next, go to the Microsoft document, FIPS 140 Validation and navigate to the topic Information
for System Integrators. Follow the instructions under "Step 2 – Setting FIPS Local/Group
Security Policy Flag" to complete the FIPS enablement.
CENT OS
The following guidance is for enabling FIPS on CentOS 7.5. These procedures are valid for
both VM and bare metal instances, and only in NATIVE mode. These procedures can be
modified for both Emulated and PV modes as needed. Note that this procedure provides an
instance that contains the exact FIPS cryptographic modules EXCEPT kernel. However, the
kernel module is the same major/minor version but is accelerated in revision, so can be
considered compliant under most FIPS compliant models.
After you complete this procedure, Oracle strongly recommends that you do NOT run system-
wide yum updates. The system-wide update will remove the FIPS modules contained herein.
VERIFY THAT THE VERSION OF THE KERNEL, FIPS MODULES, AND FIPS SOFTWARE ARE AT THE MINIMUM
VERSION:
1. Validate the current version of the kernel package meets the requirement:
a. Current version: kernel-3.10.0-693.el7
b. Execute rpm -qa | grep kernel-3
2. Execute the following and validate the major or minor version is the same as the
requirements.
a. Run
yum list <package_name>
The URLs for the packages used for this installation are:
Preinstall:
http://linuxsoft.cern.ch/cern/centos/7/updates/x86_64/Packages/nss-3.28.4-15.el7_4.x86_
64.rpm
http://linuxsoft.cern.ch/cern/centos/7/updates/x86_64/Packages/nss-util-3.28.4-3.el7.x86_
64.rpm
http://linuxsoft.cern.ch/cern/centos/7/updates/x86_64/Packages/nss-tools-3.28.4-15.el7_
4.x86_64.rpm
http://linuxsoft.cern.ch/cern/centos/7/updates/x86_64/Packages/nss-sysinit-3.28.4-15.el7_
4.x86_64.rpm
http://linuxsoft.cern.ch/cern/centos/7/updates/x86_64/Packages/nss-softokn-freebl-3.28.3-
8.el7_4.x86_64.rpm
http://linuxsoft.cern.ch/cern/centos/7/updates/x86_64/Packages/nss-softokn-3.28.3-8.el7_
4.x86_64.rpm
http://linuxsoft.cern.ch/cern/centos/7/updates/x86_64/Packages/openssl-1.0.2k-8.el7.x86_
64.rpm
http://linuxsoft.cern.ch/cern/centos/7/updates/x86_64/Packages/openssl-libs-1.0.2k-
8.el7.x86_64.rpm
http://linuxsoft.cern.ch/cern/centos/7/updates/x86_64/Packages/openssh-7.4p1-11.el7.x86_
64.rpm
http://linuxsoft.cern.ch/cern/centos/7/updates/x86_64/Packages/openssh-clients-7.4p1-
11.el7.x86_64.rpm
http://linuxsoft.cern.ch/cern/centos/7/updates/x86_64/Packages/openssh-server-7.4p1-
11.el7.x86_64.rpm
Newpackages:
http://linuxsoft.cern.ch/cern/centos/7/updates/x86_64/Packages/libreswan-3.20-3.el7.x86_
64.rpm
http://linuxsoft.cern.ch/cern/centos/7/updates/x86_64/Packages/libgcrypt-1.5.3-14.el7.x86_
64.rpm
http://linuxsoft.cern.ch/cern/centos/7/updates/x86_64/Packages/gnutls-3.3.26-9.el7.x86_
64.rpm
http://linuxsoft.cern.ch/cern/centos/7/updates/x86_64/Packages/gmp-6.0.0-15.el7.x86_
64.rpm
http://linuxsoft.cern.ch/cern/centos/7/updates/x86_64/Packages/nettle-2.7.1-8.el7.x86_
64.rpm
1. Regenerate dracut:
dracut -f -v
2. Add the fips argument to the end of the default kernel boot command line:
a. Edit /etc/default/grub
b. At the end of the line starting with “GRUB_CMDLINE_LINUX”, add
fips=1
1. Sudo to root.
2. Edit /etc/ssh/sshd_config.
3. Add the following lines to the bottom of the file:
Protocol 2
Ciphers aes128-ctr,aes192-ctr,aes256-ctr,aes128-cbc,3des-cbc,aes192-cbc,aes256-cbc
Macs hmac-sha1
The STIG for evaluating compliance under multiple profiles can be found here:
https://iase.disa.mil/stigs/os/unix-linux/Pages/index.aspx . Use the Red Hat Linux 7.x STIG
for CentOS 7.5 releases.
If you use VPN Connect with the Government Cloud, you must configure the IPSec connection
with the following FIPS-compliant IPSec parameters.
For some parameters, Oracle supports multiple values, and the recommended one is
highlighted in bold text.
Oracle supports the following parameters for IKEv1 or IKEv2. Check the documentation for
your particular CPE to confirm which parameters the CPE supports for IKEv1 or IKEv2.
PHASE 1 (ISAKMP)
Parameter Options
AES-192-cbc
AES-128-cbc
SHA-2 256
Parameter Options
* Only numbers, letters, and spaces are allowed characters in pre-shared keys.
Parameter Options
AES-128-gcm
AES-256-cbc
AES-192-cbc
AES-128-cbc
This section is for network engineers who configure an edge device for FastConnect or VPN
Connect.
Oracle's BGP ASN for the Government Cloud depends on the authorization level:
If you need to request a service limit increase, use the following instructions to create a
service request in My Oracle Support.
Important
For help with any of the general fields in the service request or for information on managing
your service requests, click Help at the top of the Oracle Cloud Support page.
Use the following tips to help you locate identifiers you might be asked to provide:
2. The tenancy OCID is shown under Tenancy Information. Click Copy to copy it to your
clipboard.
2. Click Copy to copy the OCID to your clipboard. You can then paste it into the service
request form field.
Before you can create service requests with My Oracle Support, you need to have an Oracle
Single Sign On (SSO) account and you need to register your Customer Support Identifier (CSI)
with My Oracle Support.
Tip
the form, and then click Create Account. A verification email is generated.
4. Check your email account for an email from Oracle asking your to verify your email
address.
5. Open the email and click Verify Email Address.
6. Sign in with the credentials you just set up.
7. At sign in, you are prompted to enter a Note to the Approver and the Support
Identifier (your CSI).
8. Click Request Access.
9. Enter the first five characters of the name of the organization that owns the Customer
Support Identifier (listed in the Welcome letter and on My Services), and then click
Validate. The support identifier appears in the table.
10. Click Next.
11. Enter your contact information and click Next.
12. Accept the terms and click Next.
The status of the request is pending until you receive approval from the Customer User
Administrator (CUA) or from Oracle Support if you are the first person requesting this support
identifier.
If you have previously registered, but need to add the CSI for Oracle Cloud
Infrastructure
1. Go to https://support.oracle.com and log in.
2. Navigate to the My Account page: Go to your user name at the of the page, open the
menu, and then click My Account.
3. The Support Identifiers region displays the accounts that your user name is currently
associated with.
4. Click Request Access.
5. Enter a Note to the Approver and then enter the Support Identifier (your CSI).
The status of the request is pending until you receive approval from the Customer User
Administrator (CUA).
For more information about signing in and using My Oracle Support, see Registration, Sign In,
and Accessibility Options in My Oracle Support Help.
Authorizations
Oracle Cloud Infrastructure US Government Cloud has obtained the following authorizations:
l FedRAMP High
l DISA Impact Level 5
For information about the US Government Cloud, see For All US Government Cloud
Customers.
Regions
The region names and identifiers for the US Government Cloud with FedRAMP authorization
are shown in the following table:
After your tenancy is created in one of these regions, you can subscribe to the other region.
Tenancies in the FedRAMP-authorized regions cannot subscribe to the commercial regions, or
to the US Federal Cloud regions. For information about subscribing to a region, see Managing
Regions.
To sign in to the FedRAMP-authorized US Government Cloud, enter one of the following URLs
in a supported browser:
l https://console.us-langley-1.oraclegovcloud.com/
l https://console.us-luke-1.oraclegovcloud.com/
Note
US Government Cloud with FedRAMP authorization has these APIs and corresponding regional
endpoints:
l https://iaas.us-langley-1.oraclegovcloud.com
l https://iaas.us-luke-1.oraclegovcloud.com
Database API
API reference
l https://database.us-langley-1.oraclegovcloud.com
l https://database.us-luke-1.oraclegovcloud.com
You can track the progress of long-running Database operations with the Work Requests API.
IAM API
API reference
l https://identity.us-langley-1.oraclegovcloud.com
l https://identity.us-luke-1.oraclegovcloud.com
Note
Use the Endpoint of Your Home Region for All IAM API Calls
l https://kms.us-langley-1.oraclegovcloud.com
l https://kms.us-luke-1.oraclegovcloud.com
In addition to these endpoints, each vault has a unique endpoint for create, update, and list
operations for keys. This endpoint is referred to as the control plane URL or management
endpoint. Each vault also has a unique endpoint for cryptographic operations. This endpoint is
known as the data plane URL or the cryptographic endpoint.
Monitoring API
API reference
l https://telemetry-ingestion.us-langley-1.oraclegovcloud.com
l https://telemetry-ingestion.us-luke-1.oraclegovcloud.com
l https://telemetry.us-langley-1.oraclegovcloud.com
l https://telemetry.us-luke-1.oraclegovcloud.com
l https://objectstorage.us-langley-1.oraclegovcloud.com
l https://objectstorage.us-luke-1.oraclegovcloud.com
l https://<object_storage_namespace>.compat.objectstorage.us-langley-
1.oraclegovcloud.com
l https://<object_storage_namespace>.compat.objectstorage.us-luke-
1.oraclegovcloud.com
Tip
l https://iaas.us-langley-1.oraclegovcloud.com
l https://iaas.us-luke-1.oraclegovcloud.com
The following services are currently not available for tenancies in the US Government Cloud
with FedRAMP authorization:
l Digital Assistant
l Announcements
l Analytics Cloud
l Analytics for Applications
l Application Migration
l Compliance Documents
l Container Engine for Kubernetes
l Content and Experience
l DNS Zone Management
l Email Delivery
l Events
l Functions
l Health Checks
l Integration
l Marketplace
l Notifications
l Registry
l Resource Manager
l Streaming
l Traffic Management Steering Policies
Infrastructure Tools
Integration with Oracle SaaS and PaaS services, including those listed here: Getting Started
with Oracle Platform Services
l Shared Responsibilities
l Setting Up an Identity Provider for Your Tenancy
l Using a Common Access Card/Personal Identity Verification Card to Sign in to the
Console
l IPv6 Support for Virtual Cloud Networks
l Setting Up Secure Access for Compute Hosts
l Enabling FIPS Mode for Your Operating System
l Required VPN Connect Parameters for Government Cloud
l Oracle's BGP ASN
l Requesting a Service Limit Increase for Government Cloud Tenancies
US Federal Cloud with DISA Impact Level 5 authorization supports applications that require
Impact Level 5 (IL5) data, as defined in the Department of Defense Cloud Computing Security
Requirements Guide (SRG).
The region names and identifiers for the US Federal Cloud with DISA Impact Level 5
authorization regions are shown in the following table:
After your tenancy is created in one of the US Federal Cloud with DISA Impact Level 5
authorization regions, you can subscribe to the other regions in the US Federal Cloud with
DISA Impact Level 5 authorization. These tenancies cannot subscribe to any Oracle Cloud
Infrastructure regions not belonging to the OC3 realm. For information about subscribing to a
region, see Managing Regions.
US Federal Cloud with DISA Impact Level 5 Authorization Console Sign-in URLs
To sign in to the US Federal Cloud with DISA Impact Level 5 authorization, enter one of the
following URLs in a supported browser:
l https://console.us-gov-ashburn-1.oraclegovcloud.com/
l https://console.us-gov-chicago-1.oraclegovcloud.com/
l https://console.us-gov-phoenix-1.oraclegovcloud.com/
Note
US Federal Cloud with DISA Impact Level 5 Authorization API Reference and
Endpoints
The US Federal Cloud with DISA Impact Level 5 authorization has these APIs and
corresponding regional endpoints:
l https://iaas.us-gov-ashburn-1.oraclegovcloud.com
l https://iaas.us-gov-chicago-1.oraclegovcloud.com
l https://iaas.us-gov-phoenix-1.oraclegovcloud.com
Database API
API reference
l https://database.us-gov-ashburn-1.oraclegovcloud.com
l https://database.us-gov-chicago-1.oraclegovcloud.com
l https://database.us-gov-phoenix-1.oraclegovcloud.com
You can track the progress of long-running Database operations with the Work Requests API.
IAM API
API reference
l https://identity.us-gov-ashburn-1.oraclegovcloud.com
l https://identity.us-gov-chicago-1.oraclegovcloud.com
l https://identity.us-gov-phoenix-1.oraclegovcloud.com
Note
Use the Endpoint of Your Home Region for All IAM API Calls
l https://kms.us-gov-ashburn-1.oraclegovcloud.com
l https://kms.us-gov-chicago-1.oraclegovcloud.com
l https://kms.us-gov-phoenix-1.oraclegovcloud.com
In addition to these endpoints, each vault has a unique endpoint for create, update, and list
operations for keys. This endpoint is referred to as the control plane URL or management
endpoint. Each vault also has a unique endpoint for cryptographic operations. This endpoint is
known as the data plane URL or the cryptographic endpoint.
Monitoring API
API reference
l https://telemetry-ingestion.us-gov-ashburn-1.oraclegovcloud.com
l https://telemetry-ingestion.us-gov-chicago-1.oraclegovcloud.com
l https://telemetry-ingestion.us-gov-phoenix-1.oraclegovcloud.com
l https://telemetry.us-gov-ashburn-1.oraclegovcloud.com
l https://telemetry.us-gov-chicago-1.oraclegovcloud.com
l https://telemetry.us-gov-phoenix-1.oraclegovcloud.com
l https://objectstorage.us-gov-ashburn-1.oraclegovcloud.com
l https://objectstorage.us-gov-chicago-1.oraclegovcloud.com
l https://objectstorage.us-gov-phoenix-1.oraclegovcloud.com
l https://<object_storage_namespace>.compat.objectstorage.us-gov-ashburn-
1.oraclegovcloud.com
l https://<object_storage_namespace>.compat.objectstorage.us-gov-chicago-
1.oraclegovcloud.com
l https://<object_storage_namespace>.compat.objectstorage.us-gov-phoenix-
1.oraclegovcloud.com
Tip
l https://iaas.us-gov-ashburn-1.oraclegovcloud.com
l https://iaas.us-gov-chicago-1.oraclegovcloud.com
l https://iaas.us-gov-phoenix-1.oraclegovcloud.com
Currently, the following services are not available for tenancies in the US Federal Cloud with
DISA Impact Level 5 authorization:
l Digital Assistant
l Announcements
l Analytics Cloud
l Analytics for Applications
l Application Migration
l Compliance Documents
l Container Engine for Kubernetes
l Content and Experience
l DNS Zone Management
l Email Delivery
l Events
l Functions
l Health Checks
l Integration
l Marketplace
l Notifications
l Registry
l Resource Manager
l Streaming
l Traffic Management Steering Policies
Infrastructure Tools
Integration with Oracle SaaS and PaaS services, including those listed here: Getting Started
with Oracle Platform Services.
This section shows how to give the on-premises resources that are part of NIPRNet access to
multiple US Federal Cloud regions over a single FastConnect connection. This is important if
one of the regions does not have a direct connection to the NIPRNet's border cloud access
point (BCAP). The BCAP is also referred to as the meet me point.
OVERVIEW
Some US Federal Cloud regions have a direct connection to a NIPRNet BCAP, but others do
not. You can use the Networking service to give on-premises resources that are part of
NIPRNet access to a US Federal Cloud region that is not directly connected to the NIPRNet's
BCAP. You might do this to extend your on-premises workloads into a particular US Federal
Cloud region that you're interested in, or to use that region for disaster recovery (DR).
In the diagram, US Federal Government Cloud region 1 has a direct connection to the
NIPRNet's BCAP, but US Federal Government Cloud region 2 does not. Imagine that on-
premises resources in NIPRNet (in subnet 172.16.1.0/24) need access to your virtual cloud
network (VCN) in region 2 (with CIDR 10.0.3.0/24).
Optionally, there could also be a VCN with cloud resources in region 1 (with CIDR
10.0.1.0/24), but a VCN in region 1 is not required for this scenario. The intent of this scenario
is for the on-premises resources to get access to resources in region 2.
l That FastConnect has at least one physical connection, or cross-connect. You set up a
private virtual circuit that runs on the FastConnect. The private virtual circuit enables
communication that uses private IP addresses between the on-premises resources and
the cloud resources.
l The remote peering connection is between a dynamic routing gateway (DRG) in region
1, and a DRG in region 2. A DRG is a virtual router that you typically attach to a VCN to
give that VCN access to resources outside its Oracle region.
l You can control which on-premises subnets are advertised to the VCNs by configuring
your BCAP edge router accordingly.
l The subnets in both VCN-1 and VCN-2 are advertised to your BCAP edge router over the
FastConnect connection.
l You can optionally configure VCN security rules and other firewalls that you maintain to
allow only certain types of traffic (such as SSH or SQL*NET) between the on-premises
resources and VCNs.
l The VCNs and DRGs in region 1 and region 2 must belong to the same tenancy, but they
can be in different compartments within the tenancy.
l For accurate routing, the CIDR blocks of the on-premises subnets of interest and the
VCNs must not overlap.
l To enable traffic to flow from a VCN to the on-premises subnets of interest, you must
add a route rule to the VCN subnet route tables for each of the on-premises subnets.
The preceding diagram shows the route rule for 172.16.1.0/24 in each VCN's route
table.
model. In this case, colocation occurs in the BCAP (the meet me point). The connection
consists of both a physical connection (at least one cross-connect) and logical connection
(private virtual circuit).
For instructions, follow the flow chart and tasks listed in Getting Started with FastConnect,
and notice these specific variations:
l In task 2, the instructions assume that you have a VCN (in region 1), but it is optional.
l In task 8, create a private virtual circuit (not a public one).
1. To create a VCN
2. To create a DRG
3. To attach a DRG to a VCN
Important
For instructions, see Setting Up a Remote Peering, and notice these important details:
l Optional region 1 VCN: The instructions assume that each region has a VCN, but in
this situation, it is optional for region 1.
l Single VCN administrator: The instructions assume that there are two different VCN
administrators: one for the VCN in region 1 and another for the VCN in region 2. In this
situation, there might be only a single VCN administrator (you) who handles both
regions and configures the remote peering connection.
l Unnecessary IAM policies: The instructions include a task for each VCN
administrator to set up particular IAM policies to enable the remote peering connection.
One policy is for the VCN administrator who is designated as the requestor, and one is
for the VCN administrator who is designated as the acceptor. Those terms are further
defined in Important Remote Peering Concepts. However, if there's only a single VCN
administrator with comprehensive networking permissions across the tenancy, those
IAM policies are not necessary. For more information, read the tip that appears at the
end of the task.
l RPC anchor points and connection: The remote peering actually consists of multiple
components that you must set up. There's an anchor point on each DRG (shown as RPC-
1 and RPC-2 in the preceding diagram), plus a connection between those two RPC
anchor points. The instructions include steps for creating those RPCs and the connection
between them. Ensure that you create all the components.
l Shared Responsibilities
l Setting Up an Identity Provider for Your Tenancy
l Using a Common Access Card/Personal Identity Verification Card to Sign in to the
Console
l IPv6 Support for Virtual Cloud Networks
l Setting Up Secure Access for Compute Hosts
l Enabling FIPS Mode for Your Operating System
l Required VPN Connect Parameters for Government Cloud
l Oracle's BGP ASN
l Requesting a Service Limit Increase for Government Cloud Tenancies
Regions
The region names and identifiers for the United Kingdom Government Cloud are shown in the
following table:
l https://console.uk-gov-london-1.oraclegovcloud.uk/
Analytics API
API reference
l https://analytics.uk-gov-london-1.oci.oraclegovcloud.uk
l https://iaas.uk-gov-london-1.oraclegovcloud.uk
l https://containerengine.uk-gov-london-1.oci.oraclegovcloud.uk
Database API
API reference
l https://database.uk-gov-london-1.oraclegovcloud.uk
You can track the progress of long-running Database operations with the Work Requests API.
l https://filestorage.uk-gov-london-1.oraclegovcloud.uk
IAM API
API reference
l https://identity.uk-gov-london-1.oraclegovcloud.uk
Note
Use the Endpoint of Your Home Region for All IAM API Calls
l https://kms.uk-gov-london-1.oraclegovcloud.uk
In addition to these endpoints, each vault has a unique endpoint for create, update, and list
operations for keys. This endpoint is referred to as the control plane URL or management
endpoint. Each vault also has a unique endpoint for cryptographic operations. This endpoint is
known as the data plane URL or the cryptographic endpoint.
l https://iaas.uk-gov-london-1.oraclegovcloud.uk
Monitoring API
API reference
l https://telemetry-ingestion.uk-gov-london-1.oraclegovcloud.uk
l https://telemetry.uk-gov-london-1.oraclegovcloud.uk
Notifications API
API reference
l https://cp.notification.uk-gov-london-1.oraclegovcloud.uk
l https://objectstorage.uk-gov-london-1.oraclegovcloud.uk
l https://<object_storage_namespace>.compat.objectstorage.uk-gov-london-
1.oraclegovcloud.uk
Tip
l https://resourcemanager.uk-gov-london-1.oraclegovcloud.uk
Search API
API reference
l https://query.uk-gov-london-1.oraclegovcloud.uk
Streaming API
API reference
l https://streaming.uk-gov-london-1.oraclegovcloud.uk
l https://waas.uk-gov-london-1.oraclegovcloud.uk
l https://iaas.uk-gov-london-1.oraclegovcloud.uk
l Announcements
l Application Migration
l Compliance Documents
l Health Checks
l Marketplace
Security Credentials
The types of credentials you'll use when working with Oracle Cloud Infrastructure.
Resource Identifiers
A description of the different ways your Oracle Cloud Infrastructure resources are identified.
Resource Monitoring
Information about how to monitor your resources.
Resource Tags
Information about Oracle Cloud Infrastructure tags and how to apply them to your resources.
Compartment Quotas
Information about how to control resource consumption within compartments using quotas.
Compartment Explorer
View all resources in a selected compartment, across regions.
Service Limits
A list of the default limits applied to your cloud resources and how to request an increase.
Console Announcements
Information about the announcements that occasionally appear in the Oracle Cloud
Infrastructure Console
Cloud Shell
A free-to-use browser-based terminal accessible from the Oracle Cloud Console that provides
access to a Linux shell with pre-authenticated Oracle Cloud Infrastructure CLI and other useful
tools.
Security Credentials
This section describes the types of credentials you'll use when working with Oracle Cloud
Infrastructure.
Console Password
l What it's for: Using the Console.
l Format: Typical password text string.
l How to get one: An administrator will provide you with a one-time password.
l How to use it: Sign in to the Console the first time with the one-time password, and
then change it when prompted. Requirements for the password are displayed there. The
one-time password expires in seven days. If you want to change the password later,
see To change your Console password. Also, you or an administrator can reset the
password in the Console or with the API (see To create or reset another user's Console
password). Resetting the password creates a new one-time password that you'll be
prompted to change the next time you sign in to the Console. If you're blocked from
signing in to the Console because you've tried 10 times in a row unsuccessfully, contact
your administrator.
l Note for Federated Users: Federated users do not use a Console password. Instead,
they sign in to the Console through their identity provider.
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoTFqF...
...
Auth Token
l What it's for: Authenticating with third-party APIs that do not support Oracle Cloud
Infrastructure's signature-based authentication. For example, use an auth token as your
password with Swift clients.
l Format: Typical password text string.
l How to get one: See Working with Auth Tokens.
l How to use it: Usage depends on the service your are authenticating with. Typically,
you authenticate with third-party APIs by providing your Oracle Cloud Infrastructure
Console login, your auth token provided by Oracle, and your organization's Oracle
tenant name.
Availability domains are isolated from each other, fault tolerant, and very unlikely to fail
simultaneously. Because availability domains do not share infrastructure such as power or
cooling, or the internal availability domain network, a failure at one availability domain within
a region is unlikely to impact the availability of the others within the same region.
The availability domains within the same region are connected to each other by a low latency,
high bandwidth network, which makes it possible for you to provide high-availability
connectivity to the internet and on-premises, and to build replicated systems in multiple
availability domains for both high-availability and disaster recovery.
Oracle is adding multiple cloud regions around the world to provide local access to cloud
resources for our customers. To accomplish this quickly, we’ve chosen to launch regions in
new geographies with one availability domain.
As regions require expansion, we have the option to add capacity to existing availability
domains, to add additional availability domains to an existing region, or to build a new region.
The expansion approach in a particular scenario is based on customer requirements as well as
considerations of regional demand patterns and resource availability.
For any region with one availability domain, a second availability domain or region in the
same country or geo-political area will be made available within a year to enable further
options for disaster recovery that support customer requirements for data residency where
they exist.
Regions are independent of other regions and can be separated by vast distances—across
countries or even continents. Generally, you would deploy an application in the region where
it is most heavily used, because using nearby resources is faster than using distant resources.
However, you can also deploy applications in different regions for these reasons:
Regions are grouped into realms. Your tenancy exists in a single realm and can access all
regions that belong to that realm. You cannot access regions that are not in your realm.
Currently, Oracle Cloud Infrastructure has multiple realms. There is one commercial realm.
There are multiple realms for Government Cloud: US Government Cloud FedRAMP authorized
and IL5 authorized, and United Kingdom Government Cloud.
The following table lists the regions in the Oracle Cloud Infrastructure commercial realm:
For a list of regions in the the Oracle Government Cloud realms, see the following topics:
Note
Fault Domains
A fault domain is a grouping of hardware and infrastructure within an availability domain.
Each availability domain contains three fault domains. Fault domains provide anti-
affinity: they let you distribute your instances so that the instances are not on the same
physical hardware within a single availability domain. A hardware failure or Compute
hardware maintenance event that affects one fault domain does not affect instances in other
fault domains. In addition, the physical hardware in a fault domain has independent and
redundant power supplies, which prevents a failure in the power supply hardware within one
fault domain from affecting other fault domains.
To control the placement of your compute instances, bare metal DB system instances, or
virtual machine DB system instances, you can optionally specify the fault domain for a new
instance or instance pool at launch time. If you don't specify the fault domain, the system
selects one for you. Oracle Cloud Infrastructure makes a best-effort anti-affinity placement
across different fault domains, while optimizing for available capacity in the availability
domain. To change the fault domain for an instance, terminate it and launch a new instance in
the preferred fault domain.
l For recommendations about how to use fault domains when provisioning application and
database servers, see Fault Domains in Best Practices for Your Compute Instance.
l For more information about using fault domains when provisioning Oracle bare metal
and virtual machine DB systems, see Fault Domain Considerations for Two-Node Virtual
Machine DB Systems and Availability Domain and Fault Domain Considerations for
Oracle Data Guard.
Universal monthly credit tenancies can subscribe to all publicly released commercial regions.
You can submit a request to increase the subscribed region count for your tenancies from
within the Console. If you try to subscribe to a region beyond the limit for your tenancy, you'll
be prompted to submit a limit increase request. Additionally, you can launch the request from
the service limits page or at any time by clicking the link under the Help menu ( ).
After you submit the request, it is processed. A response can take anywhere from a few
minutes to a few days. If your request is granted, a confirmation email is sent to the address
provided in the primary contact details.
If we need additional information about your request, a follow-up email is sent to the address
provided in the primary contact details.
l Compute: Compute (Intel-based bare metal & VM, DenseIO & Standard), Container
Engine for Kubernetes, Registry
l Storage: Block Volume, File Storage, Object Storage, Archive Storage
l Networking: Virtual Cloud Network, Load Balancing, FastConnect (specific partners as
available and requested)
Generally available cloud services beyond those in the previous list are made available based
on regional customer demand. Any service can be made available within a maximum of three
months, with many services deploying more quickly. New cloud services are made available
in regions as quickly as possible based on a variety of considerations, including regional
customer demand, ability to achieve regulatory compliance where applicable, resource
availability, and other factors. Because of Oracle Cloud Infrastructure's low latency
interconnect backbone, you can use cloud services in other geographic regions with effective
results when those services are not available in your home region, as long as data residency
requirements do not prevent you from doing so. We regularly work with customers to help
ensure effective access to required services.
Resource Availability
The following sections list the resource types based on their availability: across regions,
within a single region, or within a single availability domain.
Tip
Cross-Region Resources
Regional Resources
l alarms
l applications (Data Flow service)
l applications (Functions service)
l buckets: Although buckets are regional resources, they can be accessed from any
location if you use the correct region-specific Object Storage URL for the API calls.
l clusters (Big Data service)
l clusters (Container Engine for Kubernetes service)
l cloudevents-rules
l customer-premises equipment (CPE)
l data catalogs
l DB Systems (MySQL Database service)
l DHCP options sets
l dynamic routing gateways (DRGs)
l encryption keys
l functions
l images
l internet gateways
l jobs
l load balancers
l local peering gateways (LPGs)
l metrics
l models
l NAT gateways
l network security groups
l node pools
l notebook sessions
l projects
l repositories
l reserved public IPs
l route tables
l runs
l secrets
l security lists
l service gateways
l stacks
l subnets: When you create a subnet, you choose whether it's regional or specific to an
availability domain. Oracle recommends using regional subnets.
l subscriptions
l tables
IP Address Ranges
This topic provides information about public IP address ranges for services that are deployed
in Oracle Cloud Infrastructure. Allow traffic to these CIDR blocks to ensure access to the
services.
Endpoints for Oracle YUM repos and the Oracle Container Registry are listed on this page. You
can use DNS lookup to determine the public IP address for each endpoint.
The Oracle Services Network is a conceptual network in Oracle Cloud Infrastructure that is
reserved for Oracle services. A service gateway offers private access to the Oracle Services
Network from workloads in your VCN and your on-premises network. The published addresses
correspond to the service CIDR label called All <region> Services in Oracle Services
Network. For a list of the services available with a service gateway, see Service Gateway:
Supported Cloud Services in Oracle Services Network.
You can poll the published file to check for new IP address ranges as frequently as every 24
hours. We recommend that you poll the published file at least weekly.
IP addresses are published in the public_ip_ranges.json file with the fields in the following
table.
]
},
]
}
{
"region": "us-ashburn-1",
"cidrs": [
{
"cidr": "129.213.8.0/21",
"tags": [
"OCI"
]
},
{
"cidr": "134.70.24.0/21",
"tags": [
"OSN",
"OBJECT_STORAGE"
]
}
]
}
]
}
After you download the JSON file, you can use a command line tool such as jq to filter the
contents.
Download jq
Here are some examples of how you can use the tool to find and filter the information you
need:
You can use DNS lookup to determine the public IP address for each endpoint.
Resource Identifiers
This chapter describes the different ways your Oracle Cloud Infrastructure resources are
identified.
Important
To use the API, you need the OCID for your tenancy. For
information about where to find it, see the next section.
or oc3 for the Federal Government Cloud realm. The regions in the commercial realm
(OC1) belong to the domain oraclecloud.com. The regions in the Government Cloud
(OC2) belong to the domain oraclegovcloud.com.
l region: The region the resource is in (for example, phx, iad, eu-frankfurt-1). With
the introduction of the Frankfurt region, the format switched from a three-character
code to a longer string. This part is present in the OCID only for regional resources or
those specific to a single availability domain. If the region is not applicable to the
resource, this part might be blank (see the example tenancy ID below).
l future use: Reserved for future use. Currently blank.
l unique ID: The unique portion of the ID. The format may vary depending on the type of
resource or service.
Example OCIDs
Tenancy:
ocid1.tenancy.oc1..aaaaaaaaba3pv6wkcr4jqae5f44n2b2m2yt2j6rx32uzr4h25vqstifsfdsq
Instance:
ocid1.instance.oc1.phx.abuw4ljrlsfiqw6vzzxb43vyypt4pkodawglp3wqxjqofakrwvou52gb6s5a
Get the tenancy OCID from the Oracle Cloud Infrastructure Console on the Tenancy Details
page:
2. The tenancy OCID is shown under Tenancy Information. Click Copy to copy it to your
clipboard.
The tenancy OCID looks something like this (notice the word "tenancy" in it):
ocid1.tenancy.oc1..<unique_ID>
The name you assign to a user at creation is their login for the Console.
You can use these names instead of the OCID when writing a policy (for example, Allow
group <GROUP NAME> to manage all-resources in compartment <COMPARTMENT NAME>).
In addition to the name, you must also assign a description to each of your IAM resources
(although it can be an empty string). It can be a friendly description or other information that
helps you easily identify the resource. The description does not have to be unique, and you
can change it whenever you like. For example, you might want to use the description to store
the user's email address if you're not already using the email address as the user's unique
name.
Display Name
For most of the Oracle Cloud Infrastructure resources you create (other than those in IAM),
you can optionally assign a display name. It can be a friendly description or other information
that helps you easily identify the resource. The display name does not have to be unique, and
you can change it whenever you like. The Console shows the resource's display name along
with its OCID.
Resource Tags
When you have many resources (for example, instances, VCNs, load balancers, and block
volumes) across multiple compartments in your tenancy, it can become difficult to track
resources used for specific purposes, or to aggregate them, report on them, or take bulk
actions on them. Tagging allows you to define keys and values and associate them with
resources. You can then use the tags to help you organize and list resources based on your
business needs.
Defined tags are set up in your tenancy by an administrator. Only users granted permission
to work with the defined tags can apply them to resources.
Free-form tags can be applied by any user with permissions on the resource.
For more detailed information about tags and their features, see Tagging Overview.
Tip
Warning
1. Open the Console, go to the details page of the resource you want to tag.
For example, to tag a compute instance: Open the navigation menu. Under Core
Infrastructure, go to Compute and click Instances. A list of the instances in your
current compartment is displayed. Find the instance that you want to tag, and click its
name to view its details page.
2. Click Apply Tags. Depending on the resource, this option might appear in the More
Actions menu.
3. In the Apply Tags to the Resource dialog:
a. Select the Tag Namespace.
b. Select the Tag Key.
c. In Value, either enter a value or select one from the list.
d. To apply another tag, click + Additional Tag.
e. When finished adding tags, click Apply Tag(s).
For example, to view compute instances: Click Compute and then click Instances, to see
the list of instances in your current compartment.
For example, to view a compute instance: Open the navigation menu. Under Core
Infrastructure, go to Compute and click Instances. A list of the instances in your
current compartment is displayed. Find the instance that you want to remove the tag
from, and click its name to view its details page.
2. Click Tags.
The list of tags applied to the resource is displayed.
3. Find the tag you want to remove and click the pencil icon next to it.
4. Click Remove Tag.
To apply a tag to a resource using the API, use the appropriate resource's create or update
operation.
Resource Monitoring
You can monitor the health, capacity, and performance of your Oracle Cloud Infrastructure
resources when needed using queries or on a passive basis using alarms. Queries and alarms
rely on metrics emitted by your resource to the Monitoring service.
Prerequisites
l IAM policies: To monitor resources, 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. The policy must give you access to the monitoring
services as well as the resources being monitored. 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 more information on user authorizations for monitoring, see the
Authentication and Authorization section for the related service: Monitoring or
Notifications.
l Metrics exist in Monitoring: The resources that you want to monitor must emit metrics
to the Monitoring service.
l Compute instances: To emit metrics, Compute instances must be monitoring-enabled.
Oracle Cloud Agent software installation may also be required. For more information,
see Enabling Monitoring for Compute Instances.
The Monitoring service works with the Notifications service to notify you when metrics breach.
For more information about these services, see Monitoring Overview and Notifications
Overview.
1. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Instances.
2. Click the instance you're interested in.
3. On the instance details page, under Resources, click Metrics.
A chart is shown for each metric. For a list of metrics related to Compute instances, see
Compute Instance Metrics.
The Console displays the last hour of metric data for the selected resource. A chart is shown
for each metric emitted by the selected resource.
Default charts are displayed for all resources in the selected Metric Namespace and
Compartment. Very small or large values are indicated by International System of Units (SI
units), such as M for mega (10 to the sixth power).
To create a query
1. Open the navigation menu. Under Solutions and Platform, go to Monitoring and
click Metrics Explorer.
The Metrics Explorer page displays an empty chart with fields to build a query.
2. Fill in the fields for a new query.
l Compartment: The compartment containing the resources that you want to
monitor. By default, the first accessible compartment is selected.
l Metric Namespace: The service or application emitting metrics for the
resources that you want to monitor.
l Resource Group (optional): The group that the metric belongs to. A resource
group is a custom string provided with a custom metric. Not applicable to service
metrics.
l Metric Name: The name of the metric. Only one metric can be specified. Metric
selections depend on the selected compartment and metric namespace.
Example: CpuUtilization
l Interval: The aggregation window.
Interval values
Supported values for interval depend on the specified time range in the metric
query (not applicable to alarm queries). More interval values are supported for
smaller time ranges. For example, if you select one hour for the time range, then
all interval values are supported. If you select 90 days for the time range, then
only the 1h or 1d interval values are supported.
o 1m - 1 minute
o 5m - 5 minutes
o 1h - 1 hour
o 1d - 1 day
Note
1d 1 day 90 days
1h 1 hour 90 days
5m 5 minutes 30 days
1m 1 minute 7 days
Statistic values
o COUNT- The number of observations received in the specified time period.
o MAX - The highest value observed during the specified time period.
o MEAN - The value of Sum divided by Count during the specified time
period.
o MIN - The lowest value observed during the specified time period.
o P50 - The value of the 50th percentile.
o P90 - The value of the 90th percentile.
o P95 - The value of the 95th percentile.
o P99 - The value of the 99th percentile.
o P99.5 - The value of the 99.5th percentile.
Dimension fields
o Dimension Name: A qualifier specified in the metric definition. For
example, the dimension resourceId is specified in the metric definition for
CpuUtilization.
Note
o Dimension Value: The value you want to use for the specified dimension.
For example, the resource identifier for your instance of interest.
o + Additional dimension: Adds another name-value pair for a dimension.
4. To customize the y-axis label or range, type the label you want into Y-Axis Label or
type the minimum and maximum values you want into Y-Axis Min Value and Y-Axis
Max Value.
Only numeric characters are allowed for custom ranges. Custom labels and ranges are
not persisted in shared queries (MQL).
5. To view the query as a Monitoring Query Language (MQL) expression, click Advanced
Mode.
Advanced Mode is located on the right, under the chart.
Use Advanced Mode to edit your query using MQL syntax to aggregate results by group.
The MQL syntax also supports additional parameter values. For more information about
query parameters in Basic Mode and Advanced Mode, see Monitoring Query Language
(MQL) Reference.
6. To create another query, click Add Query below the chart.
To create an alarm
1. Open the navigation menu. Under Solutions and Platform, go to Monitoring and
click Alarm Definitions.
2. Click Create alarm.
Note
3. On the Create Alarm page, under Define alarm, fill in or update the alarm settings:
Note
Interval values
n 1m - 1 minute
n 5m - 5 minutes
n 1h - 1 hour
n 1d - 1 day
Note
Statistic values
n COUNT- The number of observations received in the specified time
period.
n MAX - The highest value observed during the specified time period.
n MEAN - The value of Sum divided by Count during the specified time
period.
n MIN - The lowest value observed during the specified time period.
n P50 - The value of the 50th percentile.
n P90 - The value of the 90th percentile.
n P95 - The value of the 95th percentile.
n P99 - The value of the 99th percentile.
n P99.5 - The value of the 99.5th percentile.
n RATE - The per-interval average rate of change.
n SUM - All values added together.
Dimension fields
o Dimension Name: A qualifier specified in the metric definition. For
example, the dimension resourceId is specified in the metric definition for
CpuUtilization.
Note
o Dimension Value: The value you want to use for the specified dimension.
For example, the resource identifier for your instance of interest.
o + Additional dimension: Adds another name-value pair for a dimension.
l Trigger rule: The condition that must be satisfied for the alarm to be in the firing
state. The condition can specify a threshold, such as 90% for CPU Utilization, or
an absence.
Operator values
n greater than
n greater than or equal to
n equal to
n less than
n less than or equal to
n between (inclusive of specified values)
n outside (inclusive of specified values)
n absent
Advanced Mode
Click Advanced Mode or Switch to Advanced Mode to view the alarm query as a
Monitoring Query Language (MQL) expression. Edit your query using MQL syntax to
aggregate results by group or for additional parameter values. See Monitoring Query
Language (MQL) Reference.
l Alarm Name: User-friendly name for the new alarm. This name is sent as the
title for notifications related to this alarm.
For query syntax and examples, see Working with Metric Queries.
o Trigger Delay Minutes: The number of minutes that the condition must
be maintained before the alarm is in firing state.
The chart below the Define alarm section dynamically displays the last six hours of
emitted metrics according to currently selected fields for the query. Very small or large
values are indicated by International System of Units (SI units), such as M for mega (10
to the sixth power).
4. Set up notifications: Under Notifications, fill in the fields.
l Destinations:
o Destination Service: The provider of the destination to use for
notifications.
Available options:
n Notifications Service.
o Compartment: The compartment storing the topic to be used for
notifications. Can be a different compartment from the alarm and metric.
By default, the first accessible compartment is selected.
o Topic: The topic to use for notifications. Each topic supports a subscription
protocol, such as PagerDuty.
Email subscription
Sends an email message when you publish a message to the
subscription's parent topic.
n Subscription Protocol: Select Email.
n Subscription Email: Type an email address.
PagerDuty subscription
Creates a PagerDuty incident by default when you publish a message
to the subscription's parent topic.
Endpoint format (URL):
https://events.pagerduty.com/integration/<integrationkey>/enqueue
Slack subscription
Sends a message to the specified Slack channel by default when you
publish a message to the subscription's parent topic.
Endpoint format (URL):
https://hooks.slack.com/services/<webhook-token>
Note
Service Limits
This topic describes the service limits for Oracle Cloud Infrastructure and the process for
requesting a service limit increase.
Compartment Quotas
Compartment quotas are similar to service limits; the biggest difference is that service limits
are set by Oracle, and compartment quotas are set by administrators, using policies that
allow them to allocate resources with a high level of flexibility. Compartment quotas are set
using policy statements written in a simple declarative language that is similar to the IAM
policy language.
l The Console might not yet display limits and usage information for all of the Oracle
Cloud Infrastructure services or resources.
l The usage level listed for a given resource type could be greater than the limit if the
limit was reduced after the resources were created.
l If all the resource limits are listed as 0, this means your account has been suspended.
For help, contact Oracle Support.
If you don't yet have a tenancy or a user login for the Console, or if you don't find a particular
limit listed in the Console, see Limits by Service for the default tenancy limits.
For the resource availability API (usage) the policy can be at the tenant or compartment level:
For limit definitions, services, and values APIs (only at the tenant level):
Allow group LimitsAndUsageViewers to inspect resource-availability in tenancy
For limit values APIs (does not include definitions or services), the following policy is also
supported:
Allow group LimitsAndUsageViewers to inspect limits in tenancy
Note
Required Permission
Note
1. Open the Console. Open the navigation menu, under Governance and Administration, go
to Governance, and then click Limits, Quotas and Usage.
Your resource limits, quotas, and usage for the specific region are displayed, broken out by
service. You can use the filter drop-down lists at the top of the list to filter by service, scope,
resource, and compartment.
Note
You can submit a request to increase your service limits from within the Console. If you try to
create a resource for which limit has been met, you'll be prompted to submit a limit increase
request. Additionally, you can launch the request from the service limits page or at any time
by clicking the link under the Help menu ( ).
This procedure applies to requests for service limit increases. For details about the subscribed
region limit and how to request an increase to that limit, see Subscribed Region Limits.
After you submit the request, it is processed. A response can take anywhere from a few
minutes to a few days. If your request is granted, a confirmation email is sent to the address
provided in the primary contact details.
If we need additional information about your request, a follow-up email is sent to the address
provided in the primary contact details.
Limits by Service
The following tables list the default limits for each service. Note the scope that each limit
applies to (for example, per availability domain, per region, per tenant, etc.).
Note
Compute Limits
Compute Instances
2 (other regions)
Total OCPUs for 350 cores (Australia East 6 cores (Australia East (Sydney),
shapes in the (Sydney), Australia Southeast Australia Southeast (Melbourne),
VM.Standard.E3 (Melbourne), Brazil East (Sao Brazil East (Sao Paulo), Canada
and Paulo), Canada Southeast Southeast (Montreal), Canada
BM.Standard.E3 (Montreal), Canada Southeast Southeast (Toronto), Germany
series (Toronto), Germany Central Central (Frankfurt), Japan Central
(Frankfurt), Japan Central (Osaka), Japan East (Tokyo),
(Osaka), Japan East (Tokyo), Netherlands Northwest
Netherlands Northwest (Amsterdam), Saudi Arabia West
(Amsterdam), Saudi Arabia West (Jeddah), South Korea Central
(Jeddah), South Korea Central (Seoul), South Korea North
(Seoul), South Korea North (Chuncheon), Switzerland North
(Chuncheon), Switzerland North (Zurich), UK South (London),
(Zurich), UK South (London), US East (Ashburn), US West
US East (Ashburn), US West (Phoenix))
(Phoenix))
60 (other regions)
45 (other regions)
45 (other regions)
30 (other regions)
25 (other regions)
25 (other regions)
VM.Standard.E2.1.Micro 2 2
40 (other regions)
25 (other regions)
15 (other regions)
10 (other regions)
Total OCPUs for shapes 350 cores (Australia East 6 cores (Australia East
in the VM.Standard.E3 (Sydney), Australia Southeast (Sydney), Australia Southeast
and BM.Standard.E3 (Melbourne), Brazil East (Sao (Melbourne), Brazil East (Sao
series Paulo), Canada Southeast Paulo), Canada Southeast
(Montreal), Canada Southeast (Montreal), Canada Southeast
(Toronto), Germany Central (Toronto), Germany Central
(Frankfurt), Japan Central (Frankfurt), Japan Central
(Osaka), Japan East (Tokyo), (Osaka), Japan East (Tokyo),
Netherlands Northwest Netherlands Northwest
(Amsterdam), Saudi Arabia (Amsterdam), Saudi Arabia
West (Jeddah), South Korea West (Jeddah), South Korea
Central (Seoul), South Korea Central (Seoul), South Korea
North (Chuncheon), North (Chuncheon),
Switzerland North (Zurich), Switzerland North (Zurich),
UK South (London), US East UK South (London), US East
(Ashburn), US West (Phoenix)) (Ashburn), US West (Phoenix))
VMDenseIO2.8 5 Contact Us
VMDenseIO2.16 5 Contact Us
VMDenseIO2.24 5 Contact Us
VM.Standard2.1 24 3
VM.Standard2.2 24 3
VM.Standard2.4 6 0
VM.Standard2.8 3 0
VM.Standard2.16 0 → Contact Us 0
VM.Standard2.24 0 → Contact Us 0
VM.Total 30 30
Note
Transfer package 4 4
File a service request at My Oracle Support to increase the service limits for Disk-Based Data
Import. See Requesting a Service Limit Increase for details.
To place an order for the Oracle-provided Data Transfer Appliance used for appliance-based
data transfer and data export jobs, request the required entitlement for your tenancy through
the Console or CLI. See Requesting Appliance Entitlement for instructions.
The buyer of your tenancy will be required to e-sign a Terms and Conditions document. After
Oracle receives the signed document you will have the entitlement to request and use the
Data Transfer Appliance. Appliance-Based Data Import and Data Export each come with a
service limit of 2. File a service request if you need to increase that number.
Database Limits
Database limits are per availability domain.
See Data Safe limits for information on Data Safe. See MySQL Database Limits for
information on MySQL Database.
Note
DNS Limits
DNS limits are global.
Email volume 50,000 emails per day 200 emails per day
Note
Events Limits
Events limits are regional.
Rules 50 50
File systems 100 per tenant per availability 100 per tenant per availability
domain domain
Mount targets 2 per tenant per availability 2 per tenant per availability
domain domain
Functions Limits
Limits apply to each tenancy.
Applications 10 10
Functions 20 20
IAM Limits
IAM limits are global.
Compartments in a tenancy 50 50
Statements in a policy 50 50
Integration Limits
For Integration limits, see Service Limits.
Monitoring Limits
Monitoring limits are regional.
Alarms 50 50
MySQL Database Limits
Networking Limits
Networking service limits apply to different scopes, depending on the resource.
VCN Region 50 10
Gateway Limits
IP Address Limits
VNICs Network A given network security group A given network security group
security can have as many VNICs as are can have as many VNICs as are
group in the VCN. in the VCN.
Security Network 120 (total ingress plus egress) 120 (total ingress plus egress)
rules security
group
Security rules Security list 200 ingress rules* 200 ingress rules*
and and
Dynamic routing gateways (DRGs) Region See Gateway Limits See Gateway Limits
FastConnect Limits
Dynamic routing gateways Region See Gateway Limits See Gateway Limits
(DRGs)
VLAN Limits
Notifications Limits
Notifications limits are regional.
Registry Limits
Registry limits are regional.
Registry 500 GB per OCI region or Contact 500 GB per OCI region or Contact
Storage Us Us
Vault Limits
Vault service limits apply to different scopes, depending on the resource.
Vaults in a tenancy 10 or 10 or
Contact Us Contact Us
WAF Limits
WAF limits are global.
l If you recently created a resource, it might not show up in the compartment explorer
immediately. Similarly, if you recently updated a resource, your changes might not
immediately appear.
l You must be in the same region as the resource to navigate to its details page. The
compartment explorer displays the resource's region. Use the region selector at the top
of the Console to change to the same region as the resource to enable these actions.
l When taking bulk actions, you can monitor progress on the Work Requests page.
Work Requests
Compartment explorer is one of the Oracle Cloud Infrastructure features that is integrated
with the Work Requests API. For general information on using work requests in Oracle Cloud
Infrastructure, see Work Requests in the user guide, and the Work Requests API.
Supported resources
Budgets budget
Compute autoscalingconfiguration
Compute clusternetwork
Compute consolehistory
Compute dedicatedvmhost
Compute image
Compute instance
Compute instanceconfiguration
Compute instancepool
Database autonomouscontainerdatabase
Database autonomousdatabase
Database autonomousexadatainfrastructure
Database backupdestination
Database database
Database dbhome
Database dbsystem
Database exadatainfrastructure
Database vmcluster
Database vmclusternetwork
Events eventrule
Functions functionsapplication
Functions functionsfunction
IAM compartment
IAM group
IAM identityprovider
IAM policy
IAM tagdefault
IAM tagnamespace
IAM user
Monitoring alarm
MySQL Database dbsystem
Networking cpe
Networking crossconnect
Networking crossconnectgroup
Networking ipsecconnection
Networking ipv6
Networking natgateway
Networking remotepeeringconnection
Networking routetable
Networking securitylist
Networking servicegateway
Networking subnet
Networking virtualcircuit
Networking vcn
Networking vnic
Notifications onssubscription
Notifications onstopic
OS Management osmsmanagedinstancegroup
OS Management osmsscheduledjob
OS Management osmssoftwaresource
Streaming connectharness
Streaming stream
Vault key
Vault vault
Vault vaultsecret
WAF waascertificate
WAF waaspolicy
You do not necessarily see results for everything in the compartment. For example, if your
user account is not associated with a policy that grants you the ability to, at a minimum,
inspect the instance resource type, then you can't view instances in the compartment
explorer. For more information about policies, see How Policies Work. For information about
the permissions required for the list API operation for a specific resource type, see the Policy
Reference for the appropriate service.
Work requests inherit the permissions of the operation that spawns the work request. So if
you have the permissions to move or delete a resource, you also have permission to see the
work requests associated with this action.
To enable users to list all work requests in a tenancy, use a policy like the following:
Allow group <My_Group> to inspect work-requests in tenancy
The compartment explorer opens with a view of the root compartment. Select the
compartment you want to explore from the compartment picker on the left side of the
Console. After you select a compartment, the resources that you have permission to view are
displayed. The Name and Description of the compartment you are viewing are displayed at
the top of the page.
To also list all resources in the subcompartments of the selected compartment, select Show
resources in subcompartments. When viewing resources in all subcompartments, it is
helpful to use the Compartment column in the results list to see the compartment hierarchy
where the resource resides.
Important
The Work Request page launches to show you the status of the work request to move the
resources.
Deleting Resources
Not all resource-types can be deleted using the compartment explorer. If delete is not
supported, the option is not selectable on the Actions menu.
Also, if a resource is in use by another resource, you can't delete it. For example, to delete a
VCN, it must first be empty and have no related resources or attached gateways.
The Work Request page launches to show you the status of the work request to move the
resources.
l ListBulkActionResourceTypes - use this API to help you provide the correct resource-
type information to the BulkDeleteResources and BulkMoveResources operations. The
returned list of resource-types provides the appropriate resource-type name to use as
input and the required identifying information for each resource-type. Most resource-
types only require the OCID to identity a specific resource, but some resources, such as
buckets, require you to provide other identifying information.
l BulkDeleteResources
l BulkMoveResources
Compartment Quotas
This topic describes compartment quotas for Oracle Cloud Infrastructure.
Compartment quotas give tenant and compartment administrators better control over how
resources are consumed in Oracle Cloud Infrastructure, enabling administrators to easily
allocate resources to compartments using the Console. Along with compartment budgets,
compartment quotas create a powerful toolset to manage your spending in Oracle Cloud
Infrastructure tenancies.
You can start using compartment quotas from any compartment detail page in the Console.
Compartment quotas are set using policy statements written in a simple declarative language
that is similar to the IAM policy language.
l set - sets the maximum number of a cloud resource that can be used for a
compartment
l unset - resets quotas back to the default service limits
l zero - removes access to a cloud resource for a compartment
l The action keyword, which corresponds to the type of quota being defined. This can be
set, unset, or zero.
l The name of the service family; for example: compute.
Each service in Oracle Cloud Infrastructure integrates with IAM for authentication and
authorization, for all interfaces (the Console, SDK or CLI, and REST API).
An administrator in your organization needs to set up groups, compartments, and policies that
control which users can access which services, which resources, and the type of access. For
example, the policies control who can create new users, create and manage the cloud
network, launch instances, create buckets, download objects, etc. For more information, see
Getting Started with Policies. For specific details about writing policies for each of the
different services, see Policy Reference.
If you’re a regular user (not an administrator) who needs to use the Oracle Cloud
Infrastructure resources that your company owns, contact your administrator to set up a user
ID for you. The administrator can confirm which compartment or compartments you should be
using.
To manage quotas in a compartment, you must belong to a group that has the correct
permissions. For example:
allow group QuotaAdmins to { QUOTA_READ, QUOTA_CREATE, QUOTA_DELETE, QUOTA_UPDATE, QUOTA_INSPECT } in
tenancy
For in-depth information on granting users permissions for the Quotas service, see Details for
the Quotas Service in the IAM policy reference.
Compartment quotas can be set on the root compartment. An administrator (who must be
able to manage quotas on the root compartment) can set quotas on their own compartments
and any child compartments. Quotas set on a parent compartment override quotas set on
child compartments. This way, an administrator of a parent compartment can create a quota
on a child compartment that cannot be overridden by the child.
Scope
Quotas can have different scopes, and work at the availability domain, the region, or globally.
There are a few important things to understand about scope when working with compartment
quotas:
l When setting a quota at the availability domain (AD) level, the quota is allocated to each
AD. So, for example, setting a quota of 2 X7 VMs on a compartment actually sets a limit
of 2 VMs per AD. To target a specific AD, use the request.ad parameter in the where
clause.
l Regional quotas apply to each region. For example, if a quota of 10 functions is set on a
compartment, 10 functions will be allocated per region. To target a specific region, use
the request.region parameter in the where clause.
l Usage for sub-compartments counts towards usage for the main compartment.
l Within a policy, quota statements are evaluated in order, and later statements
supersede previous statements that target the same resource.
l In cases where more than one policy is set for the same resource, the most restrictive
policy is applied.
l Service limits always take precedence over quotas. Although it is possible to specify a
quota for a resource that exceeds the service limit for that resource, the service limit
will still be enforced.
Usage Examples
The following example sets the quota for VM.DenseIO2.16 Compute instances to 10 in each
AD on compartment MyCompartment in the US West (Phoenix) region:
The next example shows how to make a whitelist, setting every quota in a family to zero and
then explicitly allocating resources:
This example shows how to limit creating a bare metal compute resource to only one region:
This example policy statement only allows one VM.Standard2.1 Compute instance in a single
compartment in a single region:
You can clear quotas by using an unset statement, which removes the quota for a resource -
any limits on this resource will now be enforced by the service limits:
To create a quota
1. Open the navigation menu. Under Governance and Administration, go to
Governance and click Quota Policies. From the Quota Policies screen, click
Create Quota.
2. Enter the following:
l Enter a name for your quota in the Name field.
l Enter a description for your quota in the Description field.
l Enter a quota policy string in the Quota Policy field.
3. Click Create Quota Policy.
Note
To edit a quota
1. From the Quota Policies screen, click the quota you want to edit to display the quota
policy details page, then click the Edit Quota button.
2. Edit the quota.
3. Click Save Changes.
To delete a quota
1. There are two ways to delete a quota from the console:
l From the main Quota Policies page, click the context menu to the right of the
quota you want to delete, then select Delete.
l Click the quota you want to delete, then from the quota policy detail page click
Delete .
2. From the Confirm Delete dialog, click Delete or Cancel.
Analytics Cloud
For Analytics Cloud quotas and examples, see Service Quotas.
Big Data
For Big Data quotas and examples, see Service Quotas.
Example
set block-storage quota volume-count to 10 in compartment MyCompartment
Compute Quotas
Note
Example
set compute quota vm-dense-io2-8-count to 10 in compartment MyCompartment where request.ad =
'<ad>:<country> - <region> - AD - <#>'
Example
set compute-management quota config-count to 10 in compartment MyCompartment
Autoscaling
Family name: auto-scaling
Example
Set auto-scaling quota config-count to 10 in compartment MyCompartment
Example
set data-catalog quota catalog-count to 1 in compartment <MyCompartment>
Example
set dataintegration quota workspace-count to 10 in compartment <compartment_name>
Example
The following example shows how to limit the number of data science projects in a specified
compartment:
set data-science quota project-count to 10 in compartment MyCompartment
Example
zero data-transfer quota job-count in tenancy
set data-transfer quota job-count to 1 in compartment Finance
set data-transfer quota appliance-count to 3 in compartment Finance
Database Quotas
Family name: database
Note
For information about shapes that are not listed, including non-metered shapes, contact
Oracle Support.
Examples
The following example shows how to limit the number of Autonomous Data Warehouse
resources in a compartment:
#Limits the Autonomous Data Warehouse CPU core count to 2 in the MyCompartment compartment
set database quota adw-ocpu-count to 2 in compartment MyCompartment
This example shows how to set a quota for OCPU cores in an Autonomous Data Warehouse
with dedicated Exadata infrastructure:
#Limits the number of Autonomous Data Warehouse dedicated Exadata infrastructure OCPUs to 20 in the
MyCompartment compartment
set database quota adw-dedicated-ocpu-count to 20 in compartment MyCompartment
This example shows how to set a quota for Autonomous Exadata Infrastructure quarter rack
resources in a compartment:
#Limits the usage of Exadata.Quarter2.92 X7 shapes to 1 in the MyCompartment compartment
set database quota exadata-quarter2-92-x7-count to 1 in compartment MyCompartment
To limit the number of virtual machine DB systems in a compartment, you must set a quota
for the number of CPU cores and a separate quota for the block storage:
#Sets a quota for virtual machine Standard Edition OCPUs to 2 in the MyCompartment compartment
set database quota vm-standard1-ocpu-count to 2 in compartment MyCompartment
#Sets the virtual machine DB system block storage quota to 1024 GB in the same compartment
set database quota vm-block-storage-gb to 1024 in compartment MyCompartment
The following example shows how to prevent the usage of all database resources in the
tenancy except for two Exadata full rack X7 resources in a specified compartment:
zero database quotas in tenancy
set database quota exadata-full2-368-x7-count to 2 in compartment MyCompartment
This example of nested quotas shows how to distribute limits for a resource type in a
compartment among its subcompartments:
#Allows usage of 3 Autonomous Data Warehouse OCPUs in parent compartment Compartment1
set database quota adw-ocpu-count to 3 in compartment Compartment1
DNS Quotas
Family name: dns
Example
zero dns quotas in compartment MyCompartment
zero dns quota global-zone-count in compartment MyCompartment
zero dns quota steering-policy-count in compartment MyCompartment
zero dns quota steering-policy-attachment-count in compartment MyCompartment
Events Quotas
Family name: events
Example
Set events quota rule-count to 10 in compartment MyCompartment
Zero events quota rule-count in compartment MyCompartment
Example
zero email-delivery quota approved-sender-count in compartment MyCompartment
Example
Set filesystem quota file-system-count to 5 in compartment MyCompartment
Zero filesystem quota file-system-count in compartment MyCompartment
Set filesystem quota mount-target-count to 1 in compartment MyCompartment
Zero filesystem quota mount-target-count in compartment MyCompartment
Networking Quotas
VCN Quotas
Family name: vcn
Example
Set vcn quota vcn-count to 10 in compartment MyCompartment
Notifications Quotas
Family name: notifications
Example
set notifications quota topic-count to 10 in compartment MyCompartment
Examples
Set object-storage quota storage-bytes to 10000000000 in tenancy
Example
set resource-manager quota concurrent-job-count to 1 in compartment MyCompartment
zero resource-manager quota stack-count in compartment MyCompartment
Streaming Quotas
Family name: streaming
Example
set streaming quota partition-count to 10 in compartment MyCompartment
Vault Quotas
Family name: kms
Example
set kms quota virtual-private-vault-count to 10 in compartment MyCompartment
set kms quota virtual-vault-count to 10 in compartment MyCompartment
WAF Quotas
Family name: waas
Example
zero waas quota waas-policy-count in compartment MyCompartment
Work Requests
This topic describes the work requests feature documented in the Work Requests API. The
following Oracle Cloud Infrastructure services are integrated with this API:
l Compute
l Database
l Compartment Explorer
Note
Work requests allow you to monitor long-running operations such as Database backups or the
provisioning of Compute instances. When you launch such an operation, the service spawns a
work request. A work request is an activity log that enables you to track each step in the
operation's progress. Each work request has an OCID that allows you to interact with it
programmatically and use it for automation.
If an operation fails, a work request can help you determine which step of the process had an
error.
Some operations affect multiple resources. For example, creating an instance pool also
affects instances and instance configurations. A work request provides a list of the resources
that an operation affects.
For workflows that require sequential operations, you can monitor each operation’s work
request and confirm that the operation has completed before proceeding to the next
operation. For example, say that you want to create an instance pool with autoscaling
enabled. To do this, you must first create the instance pool, and then configure autoscaling.
You can monitor the work request for creating the instance pool to determine when that
workflow is complete, and then configure autoscaling after it is done.
For administrators: Work requests inherit the permissions of the operation that spawns the
work request. To enable users to view the work requests, logs, and error messages for an
operation, write a policy that grants users permission to do the operation. For example, to let
users see the work requests associated with launching instances, write a policy that enables
users to launch instances.
To enable users to list all work requests in a tenancy, use the following policy:
Allow group SupportTeam to inspect work-requests in tenancy
If you're new to policies, see Getting Started with Policies and Common Policies.
ACCEPTED
IN_PROGRESS
A work request record exists for the specified request, but there is no associated WORK_
COMPLETED record.
SUCCEEDED
A work request record exists for this request and an associated WORK_COMPLETED record
has the state SUCCEEDED.
FAILED
A work request record exists for this request and an associated WORK_COMPLETED record
has the state FAILED.
CANCELING
CANCELED
l ListWorkRequests
l GetWorkRequest
l ListWorkRequestErrors
l ListWorkRequestLogs
Console Announcements
This topic describes the announcements that Oracle Cloud Infrastructure displays in the
Console. Console announcements appear at the top of the page to communicate timely,
important information about service status. You can also view a list of past and ongoing
announcements.
Note
Types of Announcements
Announcements belong to different categories. An announcement's prefix helps you
understand, at a glance, the type and relative severity of the information and whether there's
anything you can or must do. Announcement types currently include the following, in order of
most important to least:
l Required action. You must take specific action within your environment.
l Emergency change. There is a time period during which an unplanned, but urgent,
change associated with your environment will take place.
l Recommended action. You have specific action to take within your environment, but
the action is not required.
l Planned change. There is a time period during which a planned change associated
with your environment will take place.
l Planned change extended. The scheduled change period has extended beyond what
was previously communicated.
l Planned change rescheduled. The planned change to your environment has been
postponed to a later time or date.
l Production event. An impactful change to your environment either recently occurred
or is actively occurring.
l Planned change completed. The planned change to your environment has been
completed and regular operations have resumed.
l Information. There is information that you might find useful, but is not urgent and
does not require action on your part.
For announcements that require action and affect Oracle Cloud Infrastructure Compute
instances, you will get 30 days of advance notice. If you need to delay the actions described in
the announcement, contact support to request one of the alternate dates listed in the
announcement. Critical vulnerabilities might not be eligible for delay.
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.
Depending on whether you have access, you might not see any announcements. With access
to announcements, you can either see only the summary version of any given announcement
or you can also view announcement details.
For administrators: for typical policies that give users access to announcements, see Restrict
user access to view only summary announcements and Let users view details of
announcements. For more information, see Details for the Announcements Service.
If you're new to policies, see Getting Started with Policies and Common Policies.
Email Delivery
As part of your service agreement, Oracle Cloud Infrastructure also contacts you with service
status announcements through email. These emails help alert you to upcoming changes that
will impact your tenancy, such as those involving data centers or instances you use, or about
required action on your part. Whenever possible, we try to provide advance notice of
impactful events. Oracle sends these announcements to the default tenancy administrator
email address on record. You can opt out of emails with operational information that is not
urgent and does not require administrator action. (In the Console, these announcements are
marked with the type, "Information." For more information about announcement types, see
Types of Announcements.) If you want to change the default tenancy administrator email
address on record, contact Oracle Support. For more information, see Contacting Support.
Note
Viewing Announcements
This section describes how to view announcements. The Console displays announcements as
banners that span the width of the top of your browser window. As long as an announcement
remains in effect and you have the access to view announcements, the banner announcement
displays each time you sign in to the Console until you mark it as read. You can also view all
past announcements. The Announcements icon displays a green dot if you have any unread
announcements.
2. On the Announcement Details page, you can view the following information:
l Description. This describes the issue or event in greater detail than the
summary text of the announcement.
l OCID. This is the announcement's unique, Oracle-assigned identifier.
l Reference Ticket Number. You can use this number to refer to the issue when
talking to Support.
l Type. This is one of several predefined categories that helps to set expectations
about the nature and severity of the issue described.
l Affected Service. This indicates the Oracle Cloud Infrastructure services
affected by the issue or event.
l Region. This tells you what Oracle Cloud Infrastructure regions are impacted.
l Start Time. This is when the issue or event was first detected.
l End Time. This is when the issue or event was resolved.
l Required After. This is the date after which you must address any required
actions described in the announcement.
l Created. This is when the announcement was created.
l Updated. This is when the announcement was updated.
l Additional Information. This includes information such as workarounds or
background material.
l Impacted Resources. This shows the resources that were affected in some way
by the event that prompted the announcement.
3. Optionally, if you want to refer to the list of impacted resources later, click Download
Impacted Resources List.
2. The Announcements page displays all announcements. From this page, you can do the
following:
l Filter. You can filter announcements by type or by start or end date.
l Sort. You can sort announcements by summary, type, event start time, or publish
time (which indicates when the announcement was last updated).
l Mark as read. You can mark announcements as read if you want stop seeing
them as banners in the Console in subsequent sessions.
l View announcement details. You can view the details of an announcement.
l Click Start Time. The list sorts according to the start time of the event described
in the announcement. If you begin by viewing the default sort order, the sort
order will change to show the oldest announcement at the beginning of the list.
l Click Publish Time. The list sorts according to the time that an announcement
was last updated. You might find it helpful to sort by this column if you want to
track an ongoing issue or if an announcement requires action on your part.
3. To sort the list again, repeat the previous step.
For example:
oci announce announcements get --announcement-id
ocid1.announcement.region1..examplear73oue4jdywjjvietoc6im3cvb6xae4falm3faux5us3iwra3t6q
announcements:
oci announce announcements list --compartment-id <compartment_OCID>
For example:
oci announce announcements list --compartment-id
ocid1.tenancy.oc1..exampleati4wjo6cvbxq4iusld5ltpneskcfy7lr4a6wfauxuwrwed5bsdea
For example:
oci announce announcements list --compartment-id
ocid1.tenancy.oc1..exampleati4wjo6cvbxq4iusld5ltpneskcfy7lr4a6wfauxuwrwed5bsdea --announcement-type
ACTION_REQUIRED
To sort a list of announcements in ascending order of time created, from oldest to newest:
oci announce announcements list --compartment-id <compartment_OCID> --sort-order ASC
For example:
oci announce announcements list --compartment-id
ocid1.tenancy.oc1..exampleati4wjo6cvbxq4iusld5ltpneskcfy7lr4a6wfauxuwrwed5bsdea --sort-order ASC
For example:
oci announce user-status update --announcement-id
ocid1.announcement.region1..examplear73oue4jdywjjvietoc6im3cvb6xae4falm3faux5us3iwra3t6q --user-status-
announcement-id ocid1.announcement.region1..examplear73oue4jdywjjvietoc6im3cvb6xae4falm3faux5us3iwra3t6q
--user-id ocid1.user.region1..exampleaorxz3psplonigcvbzy5oaiwiubh7k7ip6zgklfauxic67kksu4oq --time-
acknowledged 2019-01-06T20:14:00+00:00
l GetAnnouncement
l GetAnnouncementUserStatus
l ListAnnouncements
l UpdateAnnouncementUserStatus
For a list of all services supported on Oracle Cloud Infrastructure, see Information About
Supported Platform Services.
To access the Console, you must use a supported browser (Oracle Cloud Infrastructure
supports the following browsers and versions:Google Chrome 69 or laterSafari 12.1 or
laterFirefox 62 or later
Along with this compartment, Oracle creates the IAM policies to allow Oracle Platform
Services access to the resources.
The compartment that Oracle creates for Oracle Platform Services is named:
ManagedCompartmentForPaaS.
The polices that Oracle creates for Oracle Platform Services are:
l PSM-root-policy
This policy is attached to the root compartment of your tenancy.
l PSM-mgd-comp-policy
This policy is attached to the ManagedCompartmentForPaaS compartment.
Warning
Some of the Platform Services automatically create some of these resources for you. See
details about your service in the following sections.
Note
Create a bucket
Following are two scenarios with procedure sets. If you need to set up all the required
resources, follow Scenario 1. If you already have a VCN in your Oracle Cloud Infrastructure
tenancy that you want to use for Oracle Platform Services, follow Scenario 2.
To follow a tutorial on how to set up the prerequisites for Scenario 1, see Creating the
Infrastructure Resources Required for Oracle Platform Services.
Create a compartment
Important
l Use of the Internet and VCN Resolver for DNS, so your instances can use their
hostnames instead of their private IP addresses to communicate with each other.
Tip
1. Open the Region menu and select the region in which you want to create the Oracle
PaaS service instance.
Select a region that's within the default data region of your account. For example, if
your default data region is EMEA, then select Germany Central (Frankfurt) or UK South
(London).
2. From the Compartment list, select the compartment you created.
3. Open the navigation menu. Under Core Infrastructure, go to Networking and click
Virtual Cloud Networks.
4. Click Networking Quickstart.
5. Select VCN with Internet Connectivity, and then click Start Workflow.
6. Enter the following:
l VCN Name: Enter a name for your cloud network, for example, <your_initials>_
Network. The name is incorporated into the names of all the related resources
that are automatically created. Avoid entering confidential information.
l Name: A unique name for the policy. The name must be unique across all policies
in your tenancy. You cannot change this later.
l Description: A friendly description. You can change this later if you want to.
l Policy Versioning: Select Keep Policy Current if you'd like the policy to stay
current with any future changes to the service's definitions of verbs and
resources. Or if you'd prefer to limit access according to the definitions that were
current on a specific date, select Use Version Date and enter that date in format
YYYY-MM-DD format. For more information, see Policy Language Version.
l Statement: To allow Oracle Platform Services access to use the network in your
compartment, enter the following policy statements. Replace <compartment_
name> with your compartment name. Click + after each statement to add
another.
Allow service PSM to inspect vcns in compartment <compartment_name>
For more information about policies, see Policy Basics and also Policy Syntax.
5. (Optional) If you want to enable the use of an Autonomous Transaction Processing or
Oracle Cloud Infrastructure Database instance in your compartment as the
infrastructure schema database for your Oracle Java Cloud Service instance, then add
the following statements:
Allow service PSM to inspect autonomous-database in compartment <compartment_name>
6. Click Create.
Create a bucket
1. Open the Region menu and select the region in which you want to create the Oracle
PaaS service instance.
Select a region that's within the default data region of your account. For example, if
your default data region is EMEA, then select Germany Central (Frankfurt) or UK South
(London).
2. Open the navigation menu. Under Core Infrastructure, click Object Storage.
3. Choose the compartment you created.
4. Click Create Bucket.
5. In the Create Bucket dialog, enter a bucket name, for example: PaasBucket.
Make a note of the name you enter. You will need it when you create an instance for
your Oracle Platform Service later.
6. Click Create Bucket.
For all other services, create an auth token. Note that your service might refer to this
credential as a Swift password. Use the auth token wherever you are asked to provide a Swift
password.
l If you're an administrator creating an auth token for another user: In the Console,
click Identity, and then click Users. Locate the user in the list, and then click the
user's name to view the details.
2. On the left side of the page, click Auth tokens.
3. Click Generate Token.
4. Enter a friendly description for the token and click Generate Token.
The new token is displayed.
5. Copy the token immediately, because you can't retrieve it again after closing the dialog
box. Also, make sure you have this token available when you create your Oracle
Platform Services instance.
You can use an existing VCN. The VCN must have at least one public subnet. Perform these
tasks to complete the prerequisites:
l Name: A unique name for the policy. The name must be unique across all policies
in your tenancy. You cannot change this later.
l Description: A friendly description. You can change this later if you want to.
l Policy Versioning: Select Keep Policy Current if you'd like the policy to stay
current with any future changes to the service's definitions of verbs and
resources. Or if you'd prefer to limit access according to the definitions that were
current on a specific date, select Use Version Date and enter that date in YYYY-
MM-DD format. For more information, see Policy Language Version.
l Statement: To allow Oracle Platform Services access to use the network, enter
the following policy. Click + after each statement to add another. In each
statement, replace <compartment_name> with the name of the compartment
where your VCN resides.
Allow service PSM to inspect vcns in compartment <compartment_name>
For more information about policies, see Policy Basics and also Policy Syntax.
5. (Optional) If you want to enable the use of an Autonomous Transaction Processing or
Oracle Cloud Infrastructure Database instance in your compartment as the
infrastructure schema database for your Oracle Java Cloud Service instance, then add
the following statements:
Allow service PSM to inspect autonomous-database in compartment <compartment_name>
6. Click Create.
Create a bucket
1. Open the Region menu and select the region in which you want to create the Oracle
PaaS service instance.
Select a region that's within the default data region of your account. For example, if
your default data region is EMEA, then select Germany Central (Frankfurt) or UK South
(London).
2. Open the navigation menu. Under Core Infrastructure, click Object Storage.
3. Choose the compartment you want to create the bucket in.
4. Click Create Bucket.
5. In the Create Bucket dialog, enter a bucket name, for example: PaasBucket. Make a
note of the name you enter. You will need it when you create an instance for your Oracle
Platform Service later.
6. Click Create Bucket.
For all other services, create an auth token. Note that your service might refer to this
credential as a Swift password. Use the auth token wherever you are asked to provide a Swift
password.
l If you're an administrator creating an auth token for another user: In the Console,
click Identity, and then click Users. Locate the user in the list, and then click the
user's name to view the details.
2. On the left side of the page, click Auth Tokens.
3. Click Generate Token.
4. Enter a friendly description for the token and click Generate Token.
The new token is displayed.
5. Copy the auth token immediately, because you can't retrieve it again after closing the
dialog box. Also, make sure you have this token available when you create your Oracle
Platform Services instance.
Data Hub Cloud About Oracle Data Hub Cloud Service Clusters in Oracle Cloud
Service Infrastructure
Java Cloud Service About Java Cloud Service Instances in Oracle Cloud Infrastructure
Oracle SOA Cloud About SOA Cloud Service Instances in Oracle Cloud Infrastructure
Service Classic and Oracle Cloud Infrastructure
Budgets
Budgets can be used to set thresholds for your Oracle Cloud Infrastructure spending. You can
set alerts on your budget to let you know when you might exceed your budget, and you can
view all of your budgets and spending from one single place in the Oracle Cloud Infrastructure
console.
Cost Analysis
Cost Analysis provides easy-to-use visualization tools to help you track and optimize your
Oracle Cloud Infrastructure spending. For more information, see Checking Your Balance and
Usage.
Usage Reports
A usage report is a comma-separated value (CSV) file that can be used to get a detailed
breakdown of resources in Oracle Cloud Infrastructure for audit or invoice reconciliation.
Invoices
You can view and download invoices for your Oracle Cloud Infrastructure usage. For more
information, see Viewing Your Subscription Invoice.
Payment Methods
The Payment Method section of the Oracle Cloud Infrastructure Console allows you to easily
manage how you pay for your Oracle Cloud Infrastructure usage.
Budgets Overview
A budget can be used to set soft limits on your Oracle Cloud Infrastructure spending. You can
set alerts on your budget to let you know when you might exceed your budget, and you can
view all of your budgets and spending from one single place in the Oracle Cloud Infrastructure
console.
Budgets are set on cost-tracking tags or on compartments (including the root compartment)
to track all spending in that cost-tracking tag or for that compartment and its children.
All budgets alerts are evaluated every 15 minutes. To see the last time a budget was
evaluated, open the details for a budget. You will see fields that show the current spend, the
forecast and the "Spent in period" field which shows you the time period over which the
budget was evaluated. When a budget alert fires, the email recipients configured in the budget
alert receive an email.
BUDGET CONCEPTS
BUDGET
A monthly threshold you define for your Oracle Cloud Infrastructure spending. Budgets
are set on cost-tracking tags or compartments and track all spending in the cost-tracking
tag or compartment and any child compartments. Note: the budget tracks spending in the
specified target compartment, but you need to have permissions to manage budgets in the
root compartment of the tenancy to create and use budgets.
ALERT
You can define email alerts that get sent out for your budget. You can send a customized
email message body with these alerts. Alerts are evaluated every 15 minutes, and can be
triggered when your actual or your forecasted spending hits either a percentage of your
budget or a specified set amount.
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.
If you're new to policies, see Getting Started with Policies and Common Policies.
To use budgets, you must be in a group that can use "usage-budgets" in the tenancy (which is
the root compartment) or be able to use all resources in the tenancy. All budgets are created
in the root compartment, regardless of the compartment they are targeting, so IAM policies
that grant budget permissions outside of the root will not be meaningful.
IAM Policy Description
Allow group accountants to inspect usage- Accountants can inspect budgets including
budgets in tenancy spend.
Allow group accountants to read usage- Accountants can read budgets including
budgets in tenancy spend (same as list).
Allow group accountants to use usage- Accountants can create and edit budgets and
budgets in tenancy alerts rules.
Allow group accountants to manage usage- Accountants can create, edit, and delete
budgets in tenancy budgets and alerts rules.
Tagging Resources
You can apply tags to your resources to help you organize them according to your business
needs. You can apply tags at the time you create a resource, or you can update the resource
later with the desired tags. For general information about applying tags, see Resource Tags.
Each service in Oracle Cloud Infrastructure integrates with IAM for authentication and
authorization, for all interfaces (the Console, SDK or CLI, and REST API).
An administrator in your organization needs to set up groups, compartments, and policies that
control which users can access which services, which resources, and the type of access. For
example, the policies control who can create new users, create and manage the cloud
network, launch instances, create buckets, download objects, etc. For more information, see
Getting Started with Policies. For specific details about writing policies for each of the
different services, see Policy Reference.
If you’re a regular user (not an administrator) who needs to use the Oracle Cloud
Infrastructure resources that your company owns, contact your administrator to set up a user
ID for you. The administrator can confirm which compartment or compartments you should be
using.
You can create automation based on state changes for your Oracle Cloud Infrastructure
resources by using event types, rules, and actions. For more information, see Overview of
Events.
Managing Budgets
To create a budget
1. Open the navigation menu. Under Governance and Administration, go to Account
Management and click Budgets.
2. Click Create Budget at the top of the budgets list. The Create Budget dialog is
displayed.
3. Select either Compartment or Cost-Tracking Tag to select the type of target for your
budget.
4. Select the target for your budget:
l For budgets targeting a compartment:
o Select a target compartment for your budget from the Target
Compartment drop-down list. Note that while the budget tracks spending
in the specified target compartment, but you need to have permissions to
manage budgets in the root compartment of the tenancy to create and use
budgets.
with metadata about your budget, including the budget name, the compartment,
and the amount of your monthly budget. You can use this message to for things
like providing instructions to the recipient that explain how to request a budget
increase or reminding users about corporate policies.
8. Advanced Options (optional): Click the Show Advanced Options link to add Tags
to your Budget. Optionally, you can apply 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.
9. Click the Create button to create your budget.
To delete a budget
1. From the list of budgets, select Delete from the context menu, or click the Delete
button at the top of budget detail screen. The Confirm Delete dialog will appear.
2. Click the Confirm button to delete the budget, or cancel by clicking Cancel.
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.
l ListBudgets
l GetBudget
l CreateBudget
l DeleteBudget
l UpdateBudget
You can set email alerts on your budgets. You can set alerts that are based on a percentage of
your budget or an absolute amount, and on your actual spending or your forecast spending.
This topic covers how to view and manage your budget alert rules.
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.
If you're new to policies, see Getting Started with Policies and Common Policies.
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.
l ListAlertRules
l GetAlertRule
l CreateAlertRule
l DeleteAlertRule
l UpdateAlertRule
A usage report is a comma-separated value (CSV) file that can be used to get a detailed
breakdown of resources in Oracle Cloud Infrastructure for audit or invoice reconciliation.
The cost report is automatically generated daily, and is stored in an Oracle-owned Object
Storage bucket. It contains one row per each Oracle Cloud Infrastructure resource (such as
instance, Object Storage bucket, VNIC) per hour along with consumption information (usage,
price, cost), metadata, and tags. Cost reports generally contain 24 hours of usage data,
although occasionally a cost report may contain late-arriving data that is older than 24 hours.
Cost reports may contain corrections. Corrections are added as new rows to the report, with
the lineItem/iscorrection column set and the referenceNo value of the corrected line
populated in the lineItem/backReference column.
The file name for each cost report is appended with an automatically incrementing numerical
value.
N
o
t
e
billedQuan
tity,
myCost, and
unitPrice
are inclusive
of Overage
numbers.
N
o
t
e
billedQuan
tity,
myCost, and
unitPrice
are inclusive
of Overage
numbers.
N
o
t
e
billedQuan
tity,
myCost, and
unitPrice
are inclusive
of Overage
numbers.
The usage report is automatically generated daily, and is stored in an Oracle-owned Object
Storage bucket. It contains one row per each Oracle Cloud Infrastructure resource (such as
instance, Object Storage bucket, VNIC) per hour along with consumption information,
metadata, and tags. Usage reports generally contain 24 hours of usage data, although
occasionally a usage report may contain late-arriving data that is older than 24 hours.
The report may contain corrections. Corrections are added as new rows to the report, with the
lineItem/iscorrection column set and the referenceNo value of the corrected line
populated in the lineItem/backReference column.
The file name for each usage report is appended with an automatically incrementing
numerical value.
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.
If you're new to policies, see Getting Started with Policies and Common Policies.
Each service in Oracle Cloud Infrastructure integrates with IAM for authentication and
authorization, for all interfaces (the Console, SDK or CLI, and REST API).
An administrator in your organization needs to set up groups, compartments, and policies that
control which users can access which services, which resources, and the type of access. For
example, the policies control who can create new users, create and manage the cloud
network, launch instances, create buckets, download objects, etc. For more information, see
Getting Started with Policies. For specific details about writing policies for each of the
different services, see Policy Reference.
If you’re a regular user (not an administrator) who needs to use the Oracle Cloud
Infrastructure resources that your company owns, contact your administrator to set up a user
ID for you. The administrator can confirm which compartment or compartments you should be
using.
Cost and usage reports are comma-separated value (CSV) files that are generated daily and
stored in an Object Storage bucket. This topic describes how to access these reports.
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.
If you're new to policies, see Getting Started with Policies and Common Policies.
Reports are generated in another tenancy and stored in an Oracle-owned Object Storage
bucket. You must set up a cross-tenancy IAM policy to access your usage reports as shown
below, changing the group name as appropriate:
define tenancy usage-report as
ocid1.tenancy.oc1..aaaaaaaaned4fkpkisbwjlr56u7cj63lf3wffbilvqknstgtvzub7vhqkggq
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.
To download a cost or usage report, use the Object Storage APIs. The reports are stored in the
tenancy's home region. The Object Storage namespace used for the reports is bling; the
bucket name is the tenancy OCID.
The following example shows how to download a cost report, usage report (or both) using a
Python script:
import oci
import os
# This script downloads all of the cost, usage, (or both) reports for a tenancy (specified in the config
file).
#
# Pre-requisites: Create an IAM policy to endorse users in your tenancy to read cost reports from the
OCI tenancy.
#
# Example policy:
# define tenancy reporting as
ocid1.tenancy.oc1..aaaaaaaaned4fkpkisbwjlr56u7cj63lf3wffbilvqknstgtvzub7vhqkggq
# endorse group group_name to read objects in tenancy reporting
#
# Note - The only value you need to change is the group name. Do not change the OCID in the first
statement.
reporting_namespace = 'bling'
# Download all usage and cost files. You can comment out based on the specific need:
prefix_file = "" # For cost and usage files
# prefix_file = "reports/cost-csv" # For cost
# prefix_file = "reports/usage-csv" # For usage
for o in report_bucket_objects.data.objects:
print('Found file ' + o.name)
object_details = object_storage.get_object(reporting_namespace, reporting_bucket, o.name)
filename = o.name.rsplit('/', 1)[-1]
bmc_ Tracks the default 30 days The last-used tenancy is not tracked, and
tenancy tenancy for the OCI users are asked to specify a tenancy when
Console login page logging into the OCI Console
s_fid Adobe Analytics unique visitor 2 years Cannot track users across different
information, anonymous Oracle products (OCI, Cloud
Marketplace)
s_nr Adobe Analytics unique visitor 2 years Cannot track users across different
information, anonymous Oracle products (OCI, Cloud
Marketplace)
gpw_ Records and saves the Never Console metrics not recorded for
e24 previously accessed URL expires analysis and product improvement
(anonymous) purposes
Important
To interact programmatically with My Services, you can use the Oracle Cloud My Services
API. To help you get started, here are some use cases:
Important
Many of the My Services API operations require you to specify the serviceEntitlementId. To
get the list of all your service entitlement IDs, use the GET ServiceEntitlements operation.
This operation returns information that you can use to make more specific requests using the
Oracle Cloud My Services API.
Example:
GET /itas/<domain>/myservices/api/v1/serviceEntitlements
Note
"id": "500089778",
"name": "Storage" // The customer is entitled to use the
Storage Service
},
"createdOn": "2017-12-20T16:23:23.326Z",
"createdBy": "[email protected]",
"modifiedOn": "2017-12-20T18:35:40.628Z",
"modifiedBy": "[email protected]",
"identityDomain": { // Identity Domain to which the Service
Entitlement is associated
"id": "511203592",
"name": "myenvironment",
"displayName": "myenvironment"
},
"cloudAccount": { // Cloud Account to which the Service
Entitlement is associated
"id": "cacct-be7475efc2c54995bc842d3379d35812",
"name": "myenvironment",
"canonicalLink": "/itas/<domain>/myservices/api/v1/cloudAccounts/cacct-
be7475efc2c54995bc842d3379d35812"
},
"status": "ACTIVE", // Current Status
"serviceConfigurations": { // Specific configuration information such
as Exadata configuration
"canonicalLink": "/itas/<domain>/myservices/api/v1/serviceEntitlements/cesi-
511202718/serviceConfigurations"
},
"canonicalLink": "/itas/{domain}/myservices/api/v1/serviceEntitlements/cesi-511202718"
},
{
"id": "cesi-511202719",
"purchaseEntitlement": {
"subscriptionId": "511203590",
"id": "511203590",
"canonicalLink": "/itas/<domain>/myservices/api/v1/purchaseEntitlements/511203590"
},
"serviceDefinition": {
"canonicalLink": "/itas/<domain>/myservices/api/v1/serviceDefinitions/500123193",
"id": "500123193",
"name": "Compute" // The customer is entitled to use the
Compute Service
},
"createdOn": "2017-12-20T16:23:23.326Z",
"createdBy": "[email protected]",
"modifiedOn": "2017-12-20T18:35:40.628Z",
"modifiedBy": "[email protected]",
"identityDomain": {
"id": "511203592",
"name": "myenvironment",
"displayName": "myenvironment"
},
"cloudAccount": {
"id": "cacct-be7475efc2c54995bc842d3379d35812",
"name": "myenvironment",
"canonicalLink": "/itas/<domain>/myservices/api/v1/cloudAccounts/cacct-
be7475efc2c54995bc842d3379d35812"
},
"status": "ACTIVE",
"serviceConfigurations": {
"canonicalLink": "/itas/<domain>/myservices/api/v1/serviceEntitlements/cesi-
511202719/serviceConfigurations"
},
"canonicalLink": "/itas/<domain>/myservices/api/v1/serviceEntitlements/cesi-511202719"
},
... // More Service Entitlements could be
displayed
],
"canonicalLink": "/itas/<domain>/myservices/api/v1/serviceEntitlements",
"hasMore": false,
"limit": 25,
"offset": 0
}
Important
The following use case examples can get you started working with the Exadata operations
available in the Oracle Cloud My Services API.
Important
To enable access to your Exadata Cloud Service instance, you can configure security rules and
associate them with your instance. The security rules define a whitelist of allowed network
access points.
The firewall provides a system of rules and groups. By default, the firewall denies network
access to the Exadata Cloud Service instance. When you enable a security rule, you enable
access to the Exadata Cloud Service instance. To enable access you must:
l Create a security group and create security rules that define specific network access
allowances.
l Assign the security group to your Exadata Cloud Service instance.
You can define multiple security groups, and each security group can contain multiple security
rules. You can associate multiple security groups with each Exadata Cloud Service instance,
and each security group can be associated with multiple Exadata Cloud Service instances. You
can dynamically enable and disable security rules by modifying the security groups that are
associated with each Exadata Cloud Service instance.
Note
Example
Example request:
GET
/itas/<domain>/myservices/api/v1/serviceInstances?serviceDefinitionNames=Exadata&statuses=ACTIVE
{
"items": [
{
"id": "csi-585928949", // Unique ServiceInstanceId
"serviceEntitlement": {
"id": "cesi-585927251",
"canonicalLink": "/itas/<domain>/myservices/api/v1/serviceEntitlements/cesi-585927251"
},
"serviceDefinition": {
"canonicalLink": "/itas/<domain>/myservices/api/v1/serviceDefinitions/502579309",
"id": "502579309",
"name": "Exadata" // The customer is entitled to use the Exadata Service
},
"cloudAccount": {
"canonicalLink": "/itas/<domain>/myservices/api/v1/cloudAccounts/cacct-fd7a122448aaaa",
"id": "cacct-fd7a122448aaaa",
"name": "myAccountName"
},
...
"canonicalLink": "/itas/<domain>/myservices/api/v1/serviceInstances/csi-585928949"
}
... // More Service Instances could be displayed
],
"canonicalLink": "/itas/<domain>/myservices/api/v1/serviceInstances",
"hasMore": false,
"limit": 25,
"offset": 0
}
This example payload returns the service instance ID csi-585928949, which is part of
the service entitlement ID cesi-585927251.
Example
Example request, using the service instance ID csi-585928949:
GET /itas/<domain>/myservices/api/v1/serviceInstances/csi-585928949/serviceConfigurations
Example
Example request, using the service entitlement ID cesi-585927251:
GET /itas/<domain>/myservices/api/v1/serviceEntitlements/cesi-
585927251/serviceConfigurations/Exadata/securityGroups
"ipSubnet": "192.168.1.0/28",
"ruleInterface": "data"
}
],
"canonicalLink":
"/itas/
<domain>
/myservices/api/v1/serviceEntitlements/585927251/serviceConfigurations/Exadata/securityGroups/2"
}
],
"canonicalLink":
"/itas/
<domain>
/myservices/api/v1/serviceEntitlements/585927251/serviceConfigurations/Exadata/securityGroups"
}
This example payload shows two security groups defined for the specified service
entitlement ID.
4. Get the current security group assignments for the service instance
Operation: GET SIExadataSecurityGroupAssignments
Example
Example request, using the service instance ID csi-585928949:
GET /itas/<domain>/myservices/api/v1/serviceInstances/csi-
585928949/serviceConfigurations/Exadata/securityGroupAssignments
<domain>
/myservices/api/v1/serviceEntitlements/585927251/serviceConfigurations/Exadata/securityGroups/1"
},
"canonicalLink": "/itas/<domain>/myservices/api/v1/serviceInstances/csi-
585928949/serviceConfigurations/Exadata/securityGroupAssignments/11"
}
],
"canonicalLink": "/itas/<domain>/myservices/api/v1/serviceInstances/csi-
585928949/serviceConfigurations/Exadata/securityGroupAssignments"
}
This example payload shows one security group assigned to the service instance csi-
585928949.
Example
Example request, using the service entitlement ID cesi-585927251:
POST /itas/<domain>/myservices/api/v1/serviceEntitlements/cesi-
585927251/serviceConfigurations/Exadata/securityGroups
{
"customerId": "585927251",
"name": "SecGroup 1",
"description": "My third Security group",
"version": 1,
"rules": [
{
"direction": "ingress",
"proto": "tcp",
"startPort": 30,
"endPort": 31,
"ipSubnet": "100.100.100.255",
"ruleInterface": "admin"
},
{
"direction": "egress",
"proto": "tcp",
"startPort": 32,
"endPort": 32,
"ipSubnet": "100.100.255.0/16",
"ruleInterface": "admin"
}
]
}
Attributes:
Name Description
Name Description
If successful, the POST request will return the unique ID of the newly created security
group. For the next step, we'll assume that the newly created security group ID is 3.
Note
Example
Example request, using the service instance csi-585928949 and the security group ID 3:
POST /itas/<domain>/myservices/api/v1/serviceInstances/csi-
585928949/serviceConfigurations/Exadata/securityGroupAssignments
{
"securityGroup": {
"id": "3",
"customerId": "585927251",
"canonicalLink":
"/itas/
<domain>
/myservices/api/v1/serviceEntitlements/585927251/serviceConfigurations/Exadata/securityGroups/3"
}
}
Attributes:
Name Description
If successful, the POST request will return the unique Id of the newly created security
group assignment.
Note
You can now verify all your security groups and assignments. See:
l Get the current security groups for the service entitlement.
l Get the current security group assignments for the service instance.
You can temporarily modify the capacity of your Exadata environment by configuring bursting.
Bursting is a method you can use to scale Exadata Cloud Service non-metered instances
within an Exadata system.
To scale up your non-metered instances, increase the number of compute nodes by modifying
the burstOcpu attribute of the host. When you no longer need the additional nodes, update the
burstOcpu attribute back to its original setting.
Note
Example
Example request:
GET
/itas/<domain>/myservices/api/v1/serviceInstances?serviceDefinitionNames=Exadata&statuses=ACTIVE
{
"items": [
{
"id": "csi-585928949", // Unique ServiceInstanceId
"serviceEntitlement": {
"id": "cesi-585927251",
"canonicalLink": "/itas/<domain>/myservices/api/v1/serviceEntitlements/cesi-585927251"
},
"serviceDefinition": {
"canonicalLink": "/itas/<domain>/myservices/api/v1/serviceDefinitions/502579309",
"id": "502579309",
"name": "Exadata" // The customer is entitled to use the Exadata Service
},
"cloudAccount": {
"canonicalLink": "/itas/<domain>/myservices/api/v1/cloudAccounts/cacct-fd7a122448aaaa",
"id": "cacct-fd7a122448aaaa",
"name": "myAccountName"
},
...
"canonicalLink": "/itas/<domain>/myservices/api/v1/serviceInstances/csi-585928949"
}
... // More Service Instances could be displayed
],
"canonicalLink": "/itas/<domain>/myservices/api/v1/serviceInstances",
"hasMore": false,
"limit": 25,
"offset": 0
}
Example
Example request, using the service instance ID csi-585928949:
GET /itas/<domain>/myservices/api/v1/serviceInstances/csi-585928949/serviceConfigurations
Example
Example request, using the service instance ID csi-585928949:
GET /itas/<domain>/myservices/api/v1/serviceInstances/csi-
585928949/serviceConfigurations/Exadata/bursting
Example
Example request, using the service instance csi-585928949:
PUT /itas/<domain>/myservices/api/v1/serviceInstances/csi-
585928949/serviceConfigurations/Exadata/bursting/
{
"ocpuOpInProgress": false,
"exaunitId": 50,
"ocpuAllocations": [
{
"hostName": "host1.oraclecloud.com",
"subscriptionOcpu": 11,
"meteredOcpu": 0,
"burstOcpu": 2,
"minOcpu": 11,
"maxOcpu": 42,
"maxBurstOcpu": 11,
"maxSubOcpu": 38,
"maxMetOcpu": 0
},
{
"hostName": "host2.oraclecloud.com",
"subscriptionOcpu": 11,
"meteredOcpu": 0,
"burstOcpu": 2,
"minOcpu": 11,
"maxOcpu": 42,
"maxBurstOcpu": 11,
"maxSubOcpu": 38,
"maxMetOcpu": 0
}
]
}
Attributes:
Name Description
Note
Example
Example request, using the service instance ID csi-585928949:
GET /itas/<domain>/myservices/api/v1/serviceInstances/csi-
585928949/serviceConfigurations/Exadata/bursting
},
{
"hostName": "host2.oraclecloud.com",
"subscriptionOcpu": 11,
"meteredOcpu": 0,
"burstOcpu": 2, // New Burst value
"minOcpu": 11,
"maxOcpu": 42,
"maxBurstOcpu": 11,
"maxSubOcpu": 38,
"maxMetOcpu": 0
}
],
"status": 200,
"op": "exaunit_coreinfo",
"additionalNumOfCores": "0",
"additionalNumOfCoresHourly": "0",
"coreBursting": "Y"
}
Important
The following procedures walk you through creating, modifying, and deleting Exadata
instances used with the Oracle Cloud My Services API.
Warning
Important
Prerequisites
l Account credentials:
o User name and password
o Identity domain ID
An identity domain ID can be either the IDCS GUID that identifies the identity
domain for the users within Identity Cloud Service (IDCS) or the Identity Domain
name for a traditional Cloud Account.
l Required roles assigned to above user name
Example:
https://itra.oraclecloud.com/itas/<domain>/myservices/api/v1/serviceEntitlements
This section covers how to create a basic Exadata instance, an instance with custom
IP network configuration, and an instance with multi-VM support.
"value": "500073421"
},
{
"name": "requestPayload.size",
"value": "CUSTOM"
},
{
"name": "requestPayload.serviceType",
"value": "Exadata"
},
{
"name": "requestPayload.adminUserName",
"value": "[email protected]"
},
{
"name": "requestPayload.adminEmail",
"value": "[email protected]"
},
{
"name": "requestPayload.adminFirstName",
"value": "John"
},
{
"name": "requestPayload.adminLastName",
"value": "Smith"
},
{
"name": "requestPayload.invokerAdminUserName",
"value": "[email protected]"
},
{
"name": "requestPayload.invokerAdminEmail",
"value": "[email protected]"
},
{
"name": "requestPayload.invokerAdminFirstName",
"value": "John"
},
{
"name": "requestPayload.invokerAdminLastName",
"value": "Smith"
},
{
"name": "requestPayload.customAttributes.ExaUnitName",
"value": "systemname"
},
{
"name": "requestPayload.customAttributes.CreateSparse",
"value": "N"
},
{
"name": "requestPayload.customAttributes.BackupToDisk",
"value": "N"
},
{
"name": "requestPayload.customAttributes.isBYOL",
"value": "N"
},
{
"name": "requestPayload.customAttributes.PickRackSize",
"value": "Quarter Rack"
},
{
"name": "requestPayload.customAttributes.SELECTED_DC_ID",
"value": "US001"
}
],
"operationItemDefinition": {
"id": "CIM-Exadata-CUSTOM-PRODUCTION-CREATE"
}
}
]
}
ATTRIBUTES
Name Description
Type: String
ExaUnitName
Name Description
CreateSparse
"Y" to create a disk group that is based on sparse grid disks, else
"N".
BackupToDisk
isBYOL "Y" to indicate that the Exadata Cloud Service instance uses Oracle
Database licenses that are provided by you rather than licenses that
are provided are part of the service subscription, else "N".
This option only affects the billing that is associated with the service
instance. It has no effect on the technical configuration of
the Exadata Cloud Service instance.
Name Description
PickRackSize Specify the rack configuration for your service instance. Exact
allowed values depend on your purchase. Typical values are like
"Full Rack", "Half Rack", "Quarter Rack" or "Eighth Rack".
SELECTED_DC_ID Data center that will host your Exadata Cloud Service instance. See
“Exadata Service Entitlement discovery” to obtain the Eligible Data
Center IDs.
{
"name": "requestPayload.size",
"value": "CUSTOM"
},
{
"name": "requestPayload.serviceType",
"value": "Exadata"
},
{
"name": "requestPayload.adminUserName",
"value": "[email protected]"
},
{
"name": "requestPayload.adminEmail",
"value": "[email protected]"
},
{
"name": "requestPayload.adminFirstName",
"value": "John"
},
{
"name": "requestPayload.adminLastName",
"value": "Smith"
},
{
"name": "requestPayload.invokerAdminUserName",
"value": "[email protected]"
},
{
"name": "requestPayload.invokerAdminEmail",
"value": "[email protected]"
},
{
"name": "requestPayload.invokerAdminFirstName",
"value": "John"
},
{
"name": "requestPayload.invokerAdminLastName",
"value": "Smith"
},
{
"name": "requestPayload.customAttributes.ExaUnitName",
"value": "systemname"
},
{
"name": "requestPayload.customAttributes.CreateSparse",
"value": "N"
},
{
"name": "requestPayload.customAttributes.BackupToDisk",
"value": "N"
},
{
"name": "requestPayload.customAttributes.isBYOL",
"value": "N"
},
{
"name": "requestPayload.customAttributes.PickRackSize",
"value": "Quarter Rack"
},
{
"name": "requestPayload.customAttributes.SELECTED_DC_ID",
"value": "US001"
}
{
"name": "requestPayload.customAttributes.ClientNetwork",
"value": "/root/root/1/ipnetwork1"
},
{
"name": "requestPayload.customAttributes.BackupNetwork",
"value": "/root/root/1/ipnetwork2"
}
],
"operationItemDefinition": {
"id": "CIM-Exadata-CUSTOM-PRODUCTION-CREATE"
}
}
]
}
ATTRIBUTES
Name Description
ClientNetwork IP network definitions for the network that is primarily used for client
access to the database servers. Applications typically access databases
on Exadata Cloud Service through this network using Oracle Net
Services in conjunction with Single Client Access Name (SCAN) and
Oracle RAC Virtual IP (VIP) interfaces.
BackupNetwork IP network definitions for the network that is typically used to access
the database servers for various purposes, including backups and bulk
data transfers.
},
{
"name": "requestPayload.adminLastName",
"value": "Smith"
},
{
"name": "requestPayload.invokerAdminUserName",
"value": "[email protected]"
},
{
"name": "requestPayload.invokerAdminEmail",
"value": "[email protected]"
},
{
"name": "requestPayload.invokerAdminFirstName",
"value": "John"
},
{
"name": "requestPayload.invokerAdminLastName",
"value": "Smith"
},
{
"name": "requestPayload.customAttributes.ExaUnitName",
"value": "systemname"
},
{
"name": "requestPayload.customAttributes.CreateSparse",
"value": "N"
},
{
"name": "requestPayload.customAttributes.BackupToDisk",
"value": "N"
},
{
"name": "requestPayload.customAttributes.isBYOL",
"value": "N"
},
{
"name": "requestPayload.customAttributes.PickRackSize",
"value": "Quarter Rack"
},
{
"name": "requestPayload.customAttributes.SELECTED_DC_ID",
"value": "US001"
}
{
"name": "requestPayload.customAttributes.EXAUNIT_ALLOCATIONS",
"value": "<base64_encoded_string>"
},
{
"name": "requestPayload.customAttributes.MULTIVM_ENABLED",
"value": "true"
}
],
"operationItemDefinition": {
"id": "CIM-Exadata-CUSTOM-PRODUCTION-CREATE"
}
}
]
}
ATTRIBUTES
Name Description
Type: String
Unique UUID
The number of CPU cores that are allocated to the VM cluster. This is
the total number of CPU cores that are allocated evenly across all of
the compute nodes in the VM cluster. Must be a multiple of
numComputes as returned by a call to ecra/endpoint/clustershapes.
Type: String
Name Description
Type: String
The total amount of Exadata storage (in TB) that is allocated to the
VM cluster. This storage is allocated evenly from all of the Exadata
Storage Servers.
The amount of local disk storage (in GB) that is allocated to each
database server in the first VM cluster.
This section covers how to add a cluster to an existing instance, reshape a cluster, and delete
a cluster.
In the following example, <domain> is the identity domain ID, <instanceId> and
<serviceEntitlementId> are returned from iTAS serviceInstances, and <base64_encoded_
string> is a base64 encoding of the payload following the example.
{
"name": "instanceId",
"value": "<instanceId>"
},
{
"name": "requestPayload.serviceEntitlementId",
"value": "<serviceEntitlementId>"
},
{
"name": "requestPayload.size",
"value": "CUSTOM"
},
{
"name": "requestPayload.serviceType",
"value": "Exadata"
},
{
"name": "requestPayload.customAttributes.EXAUNIT_ALLOCATIONS",
"value": "<base64_encoded_string>"
},
{
"name": "requestPayload.customAttributes. MULTIVM_ENABLED",
"value": "true"
}
],
"operationItemDefinition": {
"id": "CIM-Exadata-CUSTOM-PRODUCTION-UPDATE"
}
}
]
}
To reshape a cluster
Post a request with the operationItemDefinition of CIM-Exadata-CUSTOM-PRODUCTION-
UPDATE and a base64 encoding of a payload that includes the Operation value of
ReshapeCluster.
{
"name": "requestPayload.customAttributes.EXAUNIT_ALLOCATIONS",
"value": "<base64_encoded_string>"
},
{
"name": "requestPayload.customAttributes. MULTIVM_ENABLED",
"value": "true"
}
],
"operationItemDefinition": {
"id": "CIM-Exadata-CUSTOM-PRODUCTION-UPDATE"
}
}
]
}
Important
To delete a cluster
Post a request with the operationItemDefinition of CIM-Exadata-CUSTOM-PRODUCTION-
UPDATE and a base64 encoding of a payload that includes the Operation value of
DeleteCluster.
"operationItems": [
{
"attributes": [
{
"name": "instanceId",
"value": "500076173"
},
{
"name": "requestPayload.serviceEntitlementId",
"value": "500073421"
},
{
"name": "requestPayload.size",
"value": "CUSTOM"
},
{
"name": "requestPayload.serviceType",
"value": "Exadata"
},
{
"name": "requestPayload.customAttributes.EXAUNIT_ALLOCATIONS",
"value": "<base64_encoded_string>"
},
{
"name": "requestPayload.customAttributes. MULTIVM_ENABLED",
"value": "true"
}
],
"operationItemDefinition": {
"id": "CIM-Exadata-CUSTOM-PRODUCTION-UPDATE"
}
}
]
}
]
}
Important
To delete an instance
Post a request with the operationItemDefinition of CIM-Exadata-CUSTOM-PRODUCTION-
DELETE.
"value": "Exadata"
}
],
"operationItemDefinition": {
"id": "CIM-Exadata-CUSTOM-PRODUCTION-DELETE"
}
}
]
}
This section describes how to discover service entitlements and service instances.
"offset": 0
}
Use:
/itas/<domain>/myservices/api/v1/serviceEntitlements/
{ServiceEntitlementId}?expands=serviceInstancesEligibleDataCenters
}
... // More Service Entitlements could be displayed
],
"canonicalLink": "/itas/<domain>/myservices/api/v1/serviceEntitlements",
"hasMore": false,
"limit": 25,
"offset": 0
}
Important
This topic explains how to set up and use access token authorization with the Oracle Cloud My
Services API. Access token authorization allows a developer to access programmatic
endpoints (APIs) to obtain some information (for example, entitlements, instances, or
metering data) for your cloud account.
An access token contains the information required to allow a developer to access information
on your cloud account. A developer presents the token when making API calls. The allowed
actions and endpoints depend on the scopes (permissions) that you select when you generate
the token. An access token is valid for about an hour.
A refresh token allows the developer to generate a new access token without having to
contact an administrator. A refresh token is valid for about one year.
Process Overview
1. Create an Identity Cloud Service client application with the specific privileges you want
to grant to developers.
2. Generate an access token that contains the required privileges for the intended
developer.
3. Provide the access token and required information to the developer.
4. Configure Identity Cloud Service for access token validation.
1. Issue requests against My Services API endpoints. Include the access token for the
authorization parameter.
2. When the access token expires, refresh the access token without administrator
intervention until the privilege is terminated.
Perform the following tasks to enable developer access with an access token:
Important
15. To complete the creation process, click Activate at the top of the page.
Note
Make sure that you send the above information in a secure way. If you think that this
information has been compromised, see Revoking a Developer's Ability to Refresh Access
Tokens.
1. Sign in to the Oracle Identity Cloud Services admin console. See How to Access Oracle
Identity Cloud Service if you need help signing in.
2. Open the navigation menu. Under Settings select Default Settings.
3. Set the Access Signing Certificate toggle button to on.
The token file has a .tok extension. The file contains the access token and the refresh token.
The content looks like:
{"app_access_token":"eyJ4N...aabb...CpNwA","refresh_token":"AQID...9NCA="}
An access token is valid for about one hour. When the token is no longer valid you will get a
401 response code and an Error Message (“errorMessage”) value containing “Expired”.
You can generate a new short-lived access token from the refresh token. You'll need the Client
ID and Client Secret to generate the new token. You can only generate tokens with the same
or lower access (scopes) as your original token.
Using the sample token file from the previous section, the value for <refresh-token> would
be AQID...9NCA=.
Sample response:
{ "access_token": "eyJraWQiO....2nqA", "token_type": "Bearer", "expires_in": 3600, "refresh_token":
"AQIDBAUn…VkxNCB7djF9NCA=" }
Note
If you need to revoke a developer's ability to refresh access tokens, you can either invalidate
the existing refresh token by generating a new Client Secret for the token; or, you can
temporarily revoke access by deactivating the application.
Important
To restore the ability for the developer to generate an access token from a refresh token,
generate a new access token. Then provide the token along with the new Client Secret to the
developer.
The service level objectives outlined in this topic are the design points the Oracle Cloud
Infrastructure services have been engineered to meet. The definitions for availability,
manageability, or performance for each service correspond to definitions of the service
commitments in the Oracle PaaS and IaaS Public Cloud Services Pillar document. No service
credits or other financial remedy are provided due to the failure to meet a specified service
level objective.
Using the API Gateway service, you create one or more API gateways in a regional subnet to
process traffic from front-end clients and route it to back-end services. You can use a single
API gateway to link multiple back-end services (such as load balancers, compute instances,
and Oracle Functions) into a single consolidated API endpoint.
You can access the API Gateway service to define API gateways and API deployments using
the Console and the REST API.
The API Gateway service is integrated with Oracle Cloud Infrastructure Identity and Access
Management (IAM), which provides easy authentication with native Oracle Cloud
Infrastructure identity functionality.
For general information about using the API, see REST APIs.
Resource Identifiers
Most types of Oracle Cloud Infrastructure resources have a unique, Oracle-assigned identifier
called an Oracle Cloud ID (OCID). For information about the OCID format and other ways to
identify your resources, see Resource Identifiers.
An administrator in your organization needs to set up groups, compartments, and policies that
control which users can access which services, which resources, and the type of access. For
example, the policies control who can create new users, create and manage the cloud
network, launch instances, create buckets, download objects, etc. For more information, see
Getting Started with Policies. For specific details about writing policies for each of the
different services, see Policy Reference.
If you’re a regular user (not an administrator) who needs to use the Oracle Cloud
Infrastructure resources that your company owns, contact your administrator to set up a user
ID for you. The administrator can confirm which compartment or compartments you should be
using.
See Service Limits for a list of applicable limits and instructions for requesting a limit
increase.
Some other API Gateway capabilities and limits are also fixed. However, there are also a
number that you can change. See API Gateway Internal Limits.
For more details about policies for the API Gateway service, see:
API Gateways
In the API Gateway service, an API gateway is a virtual network appliance in a regional
subnet. Private API gateways can only be accessed by resources in the same subnet. Public
API gateways are publicly accessible, including from the internet.
An API gateway routes inbound traffic to back-end services including public, private, and
partner HTTP APIs, as well as Oracle Functions. Each API gateway is a private endpoint that
you can optionally expose over a public IP address as a public API gateway.
To ensure high availability, you can only create API gateways in regional subnets (not AD-
specific subnets). You can create private API gateways in private or public subnets, but you
can only create public API gateways in public subnets.
You create an API gateway within a compartment in your tenancy. Each API gateway has a
single front end, zero or more back ends, and has zero or more APIs deployed on it as
API deployments.
APIs
In the API Gateway service, an API is a set of resources, and the methods (for example, GET,
PUT) that can be performed on each resource in response to requests sent by a caller (a user
or system).
To enable an API gateway to process API requests, you must deploy the API on the API
gateway by creating an API deployment.
API Deployments
In the API Gateway service, an API deployment is the means by which you deploy an API on
an API gateway. Before the API gateway can handle requests to the API, you must create an
API deployment.
When you create an API deployment, you define properties for the API deployment, including
an API deployment specification. Every API deployment has an API deployment specification.
You can deploy multiple APIs on the same API gateway, so a single API gateway can host
multiple API deployments.
When you create the API deployment, you define properties for the API deployment, including
an API deployment specification. Every API deployment has an API deployment specification.
You can create an API deployment specification using dialogs in the Console, or using your
preferred JSON editor to create a JSON file.
Each API deployment specification defines one or more back-end resources, the route to each
back-end resource, and the methods (for example, GET, PUT) that can be performed on each
resource. The API deployment specification describes how the API gateway integrates with
the back end to execute those methods. The API deployment specification can also include
request and response policies.
Front ends
In the API Gateway service, a front end is the means by which requests flow into an API
gateway. An API gateway can have either a public front end or a private front end:
l A public front end exposes the APIs deployed on an API gateway via a public IP address.
l A private front end exposes the APIs deployed on an API gateway to a VCN via a private
endpoint.
Back ends
In the API Gateway service, a back end is the means by which a gateway routes requests to
the back-end services that implement APIs. If you add a private endpoint back end to an API
gateway, you give the API gateway access to the VCN associated with that private endpoint.
You can also grant an API gateway access to other Oracle Cloud Infrastructure services as
back ends. For example, you could grant an API gateway access to Oracle Functions, so you
can create and deploy an API that is backed by a serverless function.
An API Gateway developer is typically a user responsible for creating API deployment
specifications and deploying them to API gateways. An API Gateway developer might also
create API gateways.
An API Gateway administrator is a person responsible for setting up the API Gateway service.
For example, by setting up IAM policies. An API Gateway administrator might also create
API gateways.
Routes
In the API Gateway service, a route is the mapping between a path, one or more methods,
and a back-end service. Routes are defined in API deployment specifications.
Policies
In the API Gateway service, there are two types of policy:
You can add request policies to an API deployment specification that apply globally to all
routes in the API deployment specification, as well as request policies that apply only to
particular routes.
l You must have access to an Oracle Cloud Infrastructure tenancy. The tenancy must be
subscribed to one or more of the regions in which API Gateway is available (see
Availability by Region).
l Your tenancy must have sufficient quota on API Gateway-related resources (see Service
Limits).
l Within your tenancy, there must already be a compartment to own the necessary
network resources. If such a compartment does not exist already, you will have to
create it. See Create Compartments to Own Network Resources and API Gateway
Resources in the Tenancy, if they don't exist already.
l The compartment that owns network resources must contain a VCN, a public or private
regional subnet, and other resources (such as an internet gateway, a route table,
security lists). To ensure high availability, API gateways can only be created in regional
subnets (not AD-specific subnets). Note that an API gateway must be able to reach the
back ends defined in the API deployment specification. For example, if the back end is
on the public internet, the VCN must have an internet gateway to enable the API
gateway to route requests to the back end.
l The VCN must have a set of DHCP options that includes an appropriate DNS resolver to
Availability by Region
The API Gateway service is available in the Oracle Cloud Infrastructure regions listed at
Regions and Availability Domains. Refer to that topic to see region identifiers, region keys,
and availability domain names.
When a tenancy is created, an Administrators group is automatically created for the tenancy.
Users that are members of the Administrators group can perform any operation on resources
in the tenancy. API Gateway service users are typically not members of the Administrators
group, and do not have to be. However, a member of the Administrators group does need to
perform a number of administrative tasks to enable users to use the API Gateway service.
To set up your tenancy for API gateway development, you have to complete the following
tasks in the order shown in this checklist (the instructions in the topics below assume that you
are a tenancy administrator):
1 Create Groups and Users to Use API Gateway, if these don't exist
already
3 Create a VCN to Use with API Gateway, if one doesn't exist already
Create Groups and Users to Use API Gateway, if these don't exist already
Before users can start using the API Gateway service to create API gateways and deploy APIs
on them, as a tenancy administrator you have to create Oracle Cloud Infrastructure user
accounts, along with a group to which the user accounts belong. Later on, you'll define policies
to give the group (and the user accounts that belong to it) access to API Gateway-related
resources. If a suitable group and user accounts already exist, there's no need to create new
ones.
Before users can start using the API Gateway service to create API gateways and deploy APIs
on them, as a tenancy administrator you have to create:
Note that the same compartment can own both network resources and API Gateway-related
resources. Alternatively, you can create two separate compartments for network resources
and API Gateway-related resources.
Tip
Create a VCN to Use with API Gateway, if one doesn't exist already
Before users can start using the API Gateway service to create API gateways and deploy APIs
on them, as a tenancy administrator you have to create one or more VCNs containing a public
or private regional subnet in which to create API gateways.
The VCN can be, but need not be, owned by the same compartment to which other API
Gateway-related resources will belong. To ensure high availability, API gateways can only be
created in regional subnets (not AD-specific subnets). Note that an API gateway must be able
to reach the back ends defined in the API deployment specification. For example, if the back
end is on the public internet, the VCN must have an internet gateway to enable the API
gateway to route requests to the back end. The VCN must have a set of DHCP options that
includes an appropriate DNS resolver to map host names defined in an API deployment
specification to IP addresses.
The public or private regional subnet in which to create API gateways must have a CIDR block
that provides a minimum of 32 free IP addresses. Note that Oracle strongly recommends the
CIDR block provides more than the minimum.
To support the largest possible number of concurrent connections, Oracle also strongly
recommends that the security lists used by the subnet only have stateless rules.
If you do decide to create a new VCN, you have several options, including the following:
l You can create just the VCN initially, and then create the regional subnets and other
related resources later (as described in this topic). In this case, you can choose whether
to create a public regional subnet and an internet gateway (see Internet Gateway), or a
private regional subnet and a service gateway (see Access to Oracle Services: Service
Gateway). For example, if you don't want to expose traffic over the public internet,
create a private regional subnet and a service gateway.
l You can create the new VCN and have related resources created automatically at the
same time by selecting the Start VCN Wizard option. In this case, a public regional
subnet and a private regional subnet are created, along with an internet gateway, a NAT
gateway, and a service gateway. Although a default security list is also created, you
have to add a new stateful ingress rule for the regional subnet to allow traffic on port
443. That's because API Gateway communicates on port 443, and port 443 is not open
by default (see the corresponding step in this topic).
See Example Network Resource Configurations for details of typical network configurations.
Before users can start using the API Gateway service to create API gateways and deploy APIs
on them, as a tenancy administrator you have to create a number of Oracle Cloud
Infrastructure policies to grant access to API Gateway-related and network resources.
To grant access to API Gateway-related and network resources, you have to:
Gateway users define a new API gateway with a serverless function in Oracle Functions
as an API back end, the API Gateway service verifies that the new API gateway will
have access to the specified function. To provide access, you have to create a policy
that grants API gateways access to functions defined in Oracle Functions. See Create a
Policy to Give API Gateways Access to Functions.
See Details for API Gateway for more information about policies.
CREATE A POLICY TO GIVE API GATEWAY USERS ACCESS TO API GATEWAY-RELATED RESOURCES
When API Gateway users define a new API gateway and new API deployments, they have to
specify a compartment for those API Gateway-related resources. Users can only specify a
compartment that the groups to which they belong have been granted access. To enable users
to specify a compartment, you must create an identity policy to grant the groups access.
To create a policy to give users access to API Gateway-related resources in the compartment
that will own those resources:
l Policy Versioning: Select Keep Policy Current if you'd like the policy to stay
current with any future changes to the service's definitions of verbs and
resources. Or if you'd prefer to limit access according to the definitions that were
current on a specific date, select Use Version Date and enter that date in YYYY-
MM-DD format. For more information, see Policy Language Version.
l Statement: The following policy statement to give the group access to all API
Gateway-related resources in the compartment:
As Statement 1:, enter the following policy statement to give the group access to
all API Gateway-related resources in the compartment:
Allow group <group-name> to manage api-gateway-family in compartment <compartment-name>
For example:
Allow group acme-apigw-developers to manage api-gateway-family in compartment acme-apigw-
compartment
l Tags: Optionally, you can apply 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.
6. Click Create to create the policy giving API Gateway users access to API Gateway-
related resources in the compartment.
Tip
When API Gateway users define a new API gateway, they have to specify a VCN and a subnet
in which to create the API gateway. Users can only specify VCNs and subnets that the groups
to which they belong have been granted access. To enable users to specify a VCN and subnet,
you must create an identity policy to grant the groups access. In addition, if you want to
enable users to create public API gateways, the identity policy must allow the groups to
manage public IP addresses in the compartment that owns the network resources.
For example:
Allow group acme-apigw-developers to manage virtual-network-family in compartment acme-
network
l Tags: Optionally, you can apply 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.
6. Click Create to create the policy giving API Gateway users access to network resources
and public IP addresses in the compartment.
When API Gateway users define a new API gateway, one option is to specify a serverless
function defined in Oracle Functions as the API back end. Users can only specify functions that
the groups to which they belong have been granted access. If you want to enable users to
specify functions as API back ends, you must create an identity policy to grant the groups
access. Note that in addition to this policy for the user group, to enable users to specify
functions as API back ends you also have to create a policy to give API gateways access to
Oracle Functions (see Create a Policy to Give API Gateways Access to Functions).
Another reason to create an identity policy that grants groups access to Oracle Functions is if
you want to enable users to use the Console (rather than a JSON file) to define an
authentication request policy and specify an authorizer function defined in Oracle Functions
(see Using Authorizer Functions to Add Authentication and Authorization to API Deployments).
To create a policy to give API Gateway users access to functions defined in Oracle Functions:
For example:
Allow group acme-apigw-developers to use functions-family in compartment acme-functions-
compartment
l Tags: Optionally, you can apply 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.
6. Click Create to create the policy giving API Gateway users access to functions in the
compartment.
When API Gateway users define a new API gateway, one option is to specify a serverless
function defined in Oracle Functions as the API back end. Before creating the API gateway, the
API Gateway service verifies that the new API gateway will have access to the specified
function through an IAM policy.
Note that in addition to this policy for API gateways, to enable users to specify functions as
API back ends you also have to create a policy to give users access to Oracle Functions (see
Create a Policy to Give API Gateway Users Access to Functions).
where:
l <functions-compartment-name> is the name of the compartment
containing the functions you want to use as back ends for API gateways.
l <api-gateway-compartment-OCID> is the OCID of the compartment
containing the API gateways that you want to have access to the functions.
For example:
ALLOW any-user to use functions-family in compartment acme-functions-compartment
where
ALL { request.principal.type= 'ApiGateway' ,
request.resource.compartment.id = 'ocid1.compartment.oc1..aaaaaaaa7______ysq'
}
e. Click Create to create the policy giving API gateways access to functions defined
in Oracle Functions.
Before you can use the API Gateway service to create API gateways and deploy APIs on them
as API deployments:
l You must have access to an Oracle Cloud Infrastructure tenancy. The tenancy must be
subscribed to one or more of the regions in which API Gateway is available (see
Availability by Region).
l Your tenancy must have sufficient quota on API Gateway-related resources (see Service
Limits).
l Within your tenancy, there must already be a compartment to own the necessary
network resources. If such a compartment does not exist already, you will have to
create it. See Create Compartments to Own Network Resources and API Gateway
Resources in the Tenancy, if they don't exist already.
l The compartment that owns network resources must contain a VCN, a public or private
regional subnet, and other resources (such as an internet gateway, a route table,
security lists). To ensure high availability, API gateways can only be created in regional
subnets (not AD-specific subnets). Note that an API gateway must be able to reach the
back ends defined in the API deployment specification. For example, if the back end is
on the public internet, the VCN must have an internet gateway to enable the API
gateway to route requests to the back end.
l The VCN must have a set of DHCP options that includes an appropriate DNS resolver to
map host names defined in an API deployment specification to IP addresses. If such a
DHCP options set does not exist in the VCN already, you will have to create it. Select the
DHCP options set for the API gateway's subnet as follows:
o If the host name is publicly published on the internet, or if the host name belongs
to an instance in the same VCN, select a DHCP options set that has the Oracle-
provided Internet and VCN Resolver as the DNS Type. This is the default if you
do not explicitly select a DHCP options set.
o If the host name is on your own private or internal network (for example,
connected to the VCN by FastConnect), select a DHCP options set that has
Custom Resolver as the DNS Type, and has the URL of a suitable DNS server that
can resolve the host name to an IP address.
Note that you can change the DNS server details in the DHCP options set specified for an
API gateway's subnet. The API gateway will be reconfigured to use the updated DNS
server details within two hours. For more information about resolving host names to
IP addresses, see DNS in Your Virtual Cloud Network and DHCP Options.
l Within your tenancy, there must already be a compartment to own API Gateway-related
resources (API gateways, API deployments). This compartment can be, but need not be,
the same compartment that contains the network resources. See Create Compartments
to Own Network Resources and API Gateway Resources in the Tenancy, if they don't
exist already. Note that the API Gateway-related resources can reside in the root
compartment. However, if you expect multiple teams to create API gateways, best
practice is to create a separate compartment for each team.
l To create API gateways and deploy APIs on them, you must belong to one of the
following:
o The tenancy's Administrators group.
o A group to which policies grant the appropriate permissions on network and API
Gateway-related resources. See Create Policies to Control Access to Network and
API Gateway-Related Resources.
l Policies must be defined to give the API gateways you create access to additional
resources, if necessary. See Create a Policy to Give API Gateways Access to Functions.
This topic gives examples of how you might configure network resources for API gateways
with a serverless function as a back end:
l for a public API gateway in a public subnet (see Example 1: Example Network Resource
Configuration for a Public API Gateway in a Public Subnet with a Serverless Function as
an HTTP Back End)
l for a private API gateway in a private subnet (see Example 2: Network Resource
Configuration for a Private API Gateway in a Private Subnet with a Serverless Function
as an HTTP Back End)
These examples assume the default helloworld function has been created and deployed in
Oracle Functions with the name helloworld-func and belonging to the helloworld-app
application (see Creating, Deploying, and Invoking a Helloworld Function).
EXAMPLE 1: EXAMPLE NETWORK RESOURCE CONFIGURATION FOR A PUBLIC API GATEWAY IN A PUBLIC
S UBNET WITH A S ERVERLESS FUNCTION AS AN HTTP BACK END
This example assumes you want a public API gateway that can be accessed directly from the
internet, with a serverless function as an HTTP back end.
To achieve this example configuration, you create the following resources in the sequence
shown, with the properties shown in the Example Resource Configuration table below:
1. A VCN named 'acme-vcn1'.
2. An internet gateway named 'acme-internet-gateway'.
3. A route table named 'acme-routetable-public'.
4. A security list named 'acme-security-list-public', with an ingress rule that allows public
access to the API gateway and an egress rule that allows access to Oracle Functions.
5. A public subnet named 'acme-public-subnet'.
Issuing a curl command from the public internet against the API deployment returns the
response shown:
user@machinename ~
$ curl -X GET https://lak...sjd.apigateway.us-phoenix-1.oci.customer-oci.com/marketing/hello
Hello, world!
Resource Example
l Name: acme-vcn1
l CIDR Block: 10.0.0.0/16
l DNS Resolution: Selected
Route Table One route table created manually, named, and defined as follows:
Resource Example
Security List One security list created manually (in addition to the default security
list), named, and defined as follows:
Resource Example
Subnet One regional public subnet created manually, named, and defined as
follows:
API Gateway One public API gateway created and defined as follows:
l Name: acme-public-gateway
l Type: Public
l VCN: acme-vcn1
l Subnet: acme-public-subnet
l Hostname: (for the purpose of this example, the hostname is
lak...sjd.apigateway.us-phoenix-1.oci.customer-oci.com)
Resource Example
l Name: acme-public-deployment
l Path Prefix: /marketing
l API Request Policies: None specified
l API Logging Policies: None specified
l Route:
o Path: /hello
o Methods: GET
o Type: Oracle Functions
o Application: helloworld-app
o Function Name: helloworld-func
EXAMPLE 2: NETWORK RESOURCE CONFIGURATION FOR A PRIVATE API GATEWAY IN A PRIVATE S UBNET
WITH A S ERVERLESS FUNCTION AS AN HTTP BACK END
This example assumes you want a private API gateway that can only be accessed via a
bastion host (rather than accessed directly from the internet), with a serverless function as an
HTTP back end.
To achieve this example configuration, you create the following resources in the sequence
shown, with the properties shown in the Example Resource Configuration table below:
1. A VCN named acme-vcn2
2. An internet gateway named acme-internet-gateway
Having SSH'd into the bastion host, issuing a curl command against the API deployment
returns the response shown:
[user@machinename ~]$ ssh [email protected]
Hello, world!
Resource Example
l Name: acme-vcn2
l CIDR Block: 10.0.0.0/16
l DNS Resolution: Selected
Route Tables Two route tables created manually, named, and defined as follows:
Resource Example
Resource Example
Security List Two security lists created manually (in addition to the default security
list), named, and defined as follows:
Resource Example
Subnet Two regional subnets created manually, named, and defined as follows:
Resource Example
API Gateway One private API gateway created and defined as follows:
l Name: acme-private-gateway
l Type: Private
l VCN: acme-vcn2
l Subnet: acme-private-subnet
l Hostname: (for the purpose of this example, the hostname is
pwa...djt.apigateway.us-phoenix-1.oci.customer-oci.com)
l Name: acme-private-deployment
l Path Prefix: /marketing-private
l API Request Policies: None specified
l API Logging Policies: None specified
l Route:
o Path: /hello
o Methods: GET
o Type: Oracle Functions
o Application: helloworld-app
o Function Name: helloworld-func
Resource Example
l Name: acme-bastion-instance
l Availability Domain: AD1
l Instance Type: Virtual Machine
l VCN: acme-vcn2
l Subnet:acme-bastion-public-subnet
l Assign a public IP address: Selected (for the purpose of this
example, the instance is given the IP address 198.51.100.254)
You can use the API Gateway REST API using the Oracle Cloud Infrastructure CLI (for more
information and configuration instructions, see Configuring Your Client Environment to use the
CLI for API Gateway Development).
Configuring Your Client Environment to use the CLI for API Gateway Development
In addition to using the Console to create API gateways and API deployments, you'll typically
also want to create and manage API gateways and API deployments programmatically using
the API Gateway service's REST API.
One way to use the API Gateway REST API is to use the Oracle Cloud Infrastructure CLI.
Before you can start using the Oracle Cloud Infrastructure CLI to create and manage API
gateways and API deployments programmatically using the API Gateway REST API, you have
to set up your client environment appropriately. Note that prior to setting up your client
environment, you must already have set up your tenancy (see Configuring Your Tenancy for
API Gateway Development).
To set up your client environment for API development using the Oracle Cloud Infrastructure
CLI, you have to complete the following tasks in the order shown in this checklist:
Click each of the links in the checklist in turn, and follow the instructions.
You can use a single API gateway as the front end for multiple back-end services by:
l Creating a single API deployment on the API gateway, with an API deployment
specification that defines multiple back-end services.
l Creating multiple API deployments on the same API gateway, each with an API
deployment specification that defines one (or more) back-end services.
Having a single API gateway as a front end enables you to present a single cohesive API to
callers, even if the API is actually comprised of smaller microservices written by different
software teams using different programming languages or technologies.
1. In the Console, open the navigation menu. Under Solutions and Platform, go to
Developer Services and click API Gateway.
2. Choose a Compartment you have permission to work in.
3. On the Gateways page, click Create Gateway and specify:
l Name: The name of the new API gateway. Avoid entering confidential
information.
l Type: The type of API gateway to create. Select Private if you want the
API gateway (and the APIs deployed on it) to be accessible only from the same
subnet in which the API gateway is created. Select Public if you want the
API gateway (and the APIs deployed on it) to be accessible from the internet. In
the case of a public API gateway, an internet gateway must exist to give access to
the VCN.
l Compartment: The compartment to which the new API gateway is to belong.
l VCN in <compartment-name>: The VCN in which to create the API gateway.
The VCN can belong to the same compartment as the new API gateway, but does
not have to.
l Subnet in <compartment-name>: The name of a public or private regional
subnet in which to create the API gateway. If you want to create a public API
gateway, you must specify a public regional subnet.
l Tags:Optionally, you can apply 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.
4. Click Create to create the new API gateway.
Note that it can take a few minutes to create the new API gateway. While it is being
created, the API gateway is shown with a state of Creating on the Gateways page.
When it has been created successfully, the new API gateway is shown with a state of
Active.
5. If you have waited more than a few minutes for the API gateway to be shown with an
Active state (or if the API gateway creation operation has failed):
a. Click the name of the API gateway, and click Work Requests to see an overview
of the API gateway creation operation.
b. Click the Create Gateway operation to see more information about the
operation (including error messages, log messages, and the status of associated
resources).
c. If the API gateway creation operation has failed and you cannot diagnose the
cause of the problem from the work request information, see Troubleshooting API
Gateway.
Having successfully created an API gateway, you can deploy an API on it (see Deploying an
API on an API Gateway by Creating an API Deployment).
1. Configure your client environment to use the CLI (Configuring Your Client Environment
to use the CLI for API Gateway Development).
2. Open a command prompt and run oci api-gateway gateway create to create the
API gateway:
oci api-gateway gateway create --display-name "<gateway-name>" --compartment-id <compartment-
ocid> --endpoint-type "<gateway-type>" --subnet-id <subnet-ocid>
where:
l <gateway-name> is the name of the new API gateway. Avoid entering confidential
information.
If you want the command to wait to return control until the API gateway is active (or the
request has failed), include either or both the following parameters:
l --wait-for-state ACTIVE
l --wait-for-state FAILED
For example:
oci api-gateway gateway create --display-name "Hello World Gateway" --compartment-id
ocid1.compartment.oc1..aaaaaaaa7______ysq --endpoint-type "PRIVATE" --subnet-id
ocid1.subnet.oc1.iad.aaaaaaaaz______rca --wait-for-state ACTIVE
Note that you cannot use the API gateway until the work request has successfully
created it and the API gateway is active.
3. (Optional) To see the status of the API gateway, enter:
oci api-gateway gateway get --gateway-id <gateway-ocid>
4. (Optional) To see the status of the work request that is creating the API gateway, enter:
oci api-gateway work-request get --work-request-id <work-request-ocid>
5. (Optional) To view the logs of the work request that is creating the API gateway, enter:
oci api-gateway work-request-log list --work-request-id <work-request-ocid>
6. (Optional) If the work request that is creating the API gateway fails and you want to
review the error logs, enter:
oci api-gateway work-request-error --work-request-id <work-request-ocid>
For more information about using the CLI, see Command Line Interface (CLI). For a complete
list of flags and options available for CLI commands, see CLI Help.
Each API deployment specification defines a set of resources, and the methods (for example,
GET, PUT) that can be performed on each resource.
You can use a single API gateway as the front end for multiple back-end services by:
l Creating a single API deployment on the API gateway, with an API deployment
specification that defines multiple back-end services.
l Creating multiple API deployments on the same API gateway, each with an API
deployment specification that defines one (or more) back-end services.
Typically, back-end services will be in the same VCN as the API gateway on which you deploy
an API. However, they don't have to be. In the API deployment specification, you can define
back-end services that are on a private or public subnet in your tenancy, as well as services
outside your tenancy (including on the public internet). Wherever they are located, the back-
end services must be routable from the subnet containing the API gateway on which the API is
deployed. For example, if the back-end service is on the public internet, the VCN must have
an internet gateway to enable the API gateway to route requests to the back-end service.
The instructions in this topic show a basic API deployment specification with a single backend,
only one route, and no request or response policies. See Example API Deployment
Specification with Multiple Back Ends for a more typical API deployment specification that
includes multiple back ends, each with one or more routes.
In addition, you can add request and response policies that apply to routes in an API
deployment specification (see Adding Request Policies and Response Policies to API
Deployment Specifications).
1. Using your preferred JSON editor, create the API deployment specification in a JSON file
in the format:
{
"requestPolicies": {},
"routes": [
{
"path": "<api-route-path>",
"methods": ["<method-list>"],
"backend": {
"type": "<backend-type>",
"<backend-target>": "<identifier>"
},
"requestPolicies": {}
}
]
}
where:
l "requestPolicies" specifies optional policies to control the behavior of an API
deployment. If you want to apply policies to all routes in an API deployment
specification, place the policies outside the routes section. If you want to apply
the policies just to a particular route, place the policies inside the routes section.
See Adding Request Policies and Response Policies to API Deployment
Specifications.
l <api-route-path> specifies a path for API calls using the listed methods to the
For a more complex example that defines multiple back ends, see Example API
Deployment Specification with Multiple Back Ends.
2. Save the JSON file containing the API deployment specification.
3. Use the API deployment specification when you create or update an API deployment in
the following ways:
l by specifying the JSON file in the Console when you select the Upload an
existing API option
l by specifying the JSON file in a request to the API Gateway REST API
For more information, see Deploying an API on an API Gateway by Creating an
API Deployment.
For example, the following API deployment specification defines a simple Hello World
serverless function in Oracle Functions as one back end, and the National Weather Service API
as a second back end.
{
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
}
},
{
"path": "/weather",
"methods": ["GET"],
"backend": {
"type": "HTTP_BACKEND",
"url": "https://api.weather.gov"
}
}
]
}
You can use a single API gateway as the front end for multiple back-end services by:
l Creating a single API deployment on the API gateway, with an API deployment
specification that defines multiple back-end services.
l Creating multiple API deployments on the same API gateway, each with an API
deployment specification that defines one (or more) back-end services.
1. In the Console, open the navigation menu. Under Solutions and Platform, go to
Developer Services and click API Gateway.
2. Choose a Compartment you have permission to work in.
3. On the Gateways page, click the name of the API gateway on which you want to deploy
the API to show the Gateway Details page.
4. On the Gateway Details page, select Deployments from the Resources list, and
then click Create Deployment.
5. Click From Scratch and in the Basic Information section, specify:
l Name: The name of the new API deployment. Avoid entering confidential
information.
l Path Prefix: A path on which to deploy all routes contained in the API
deployment specification. For example:
o /v1
o /v2
o /test/20191122
14. If you have waited more than a few minutes for the API deployment to be shown with an
Active state (or if the API deployment creation operation has failed):
a. Click the name of the API deployment, and click Work Requests to see an
overview of the API deployment creation operation.
b. Click the Create Deployment operation to see more information about the
operation (including error messages, log messages, and the status of associated
resources).
c. If the API deployment creation operation has failed and you cannot diagnose the
cause of the problem from the work request information, see Troubleshooting API
Gateway.
15. (Optional) Confirm the API has been deployed successfully by calling it (see Calling an
API Deployed on an API Gateway).
1. In the Console, open the navigation menu. Under Solutions and Platform, go to
Developer Services and click API Gateway.
2. Choose a Compartment you have permission to work in.
3. On the Gateways page, click the name of the API gateway on which you want to deploy
the API to show the Gateway Details page.
4. On the Gateway Details page, select Deployments from the Resources list, and
then click Create Deployment.
5. Click Upload an existing API.
6. In the Upload Information section, specify:
l Name: The name of the new API deployment. Avoid entering confidential
information.
l Path Prefix: A path on which to deploy all routes contained in the API
10. If you have waited more than a few minutes for the API deployment to be shown with an
Active state (or if the API deployment creation operation has failed):
a. Click the name of the API deployment, and click Work Requests to see an
overview of the API deployment creation operation.
b. Click the Create Deployment operation to see more information about the
operation (including error messages, log messages, and the status of associated
resources).
c. If the API deployment creation operation has failed and you cannot diagnose the
cause of the problem from the work request information, see Troubleshooting API
Gateway.
11. (Optional) Confirm the API has been deployed successfully by calling it (see Calling an
API Deployed on an API Gateway).
1. Configure your client environment to use the CLI (Configuring Your Client Environment
to use the CLI for API Gateway Development).
2. Open a command prompt and run oci api-gateway deployment create to create the
deployment:
oci api-gateway deployment create --compartment-id <compartment-ocid> --display-name <api-name>
--gateway-id <gateway-ocid> --path-prefix "/<deployment-path-prefix>" --specification
file:///<filename>
where:
l <compartment-ocid> is the OCID of the compartment in which to create the new
API deployment.
l <api-name> is the name of the new API deployment. Avoid entering confidential
information.
l <gateway-ocid> is the OCID of the existing gateway on which to deploy the API.
To find out the API gateway's OCID, see Listing API Gateways and API
Deployments.
l /<deployment-path-prefix> is a path on which to deploy all routes contained in
the API deployment specification.
Note that the deployment path prefix you specify:
o must be preceded by a forward slash ( / ) in the JSON file
o can contain multiple forward slashes (provided they are not adjacent), but
must not end with a forward slash
o can include alphanumeric uppercase and lowercase characters
o can include the special characters $ - _ . + ! * ' ( ) , % ; : @ & =
o cannot include parameters and wildcards
l <filename> is the API deployment specification, including a path, one or more
methods, and a back end definition. See Creating an API Deployment
Specification.
For example:
oci api-gateway deployment create --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --
display-name "Marketing Deployment" --gateway-id ocid1.apigateway.oc1..aaaaaaaab______hga --path-
prefix "/marketing" --specification file:///Users/jdoe/work/deployment.json
For example:
oci api-gateway deployment create --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --
display-name "Marketing Deployment" --gateway-id ocid1.apigateway.oc1..aaaaaaaab______hga --path-
prefix "/marketing" --specification file:///Users/jdoe/work/deployment.json --wait-for-state
ACTIVE
Note that you cannot use the API deployment until the work request has successfully
created it and the API deployment is active.
3. (Optional) To see the status of the API deployment, enter:
oci api-gateway deployment get --deployment-id <deployment-ocid>
4. (Optional) To see the status of the work request that is creating the API deployment,
enter:
oci api-gateway work-request get --work-request-id <work-request-ocid>
5. (Optional) To view the logs of the work request that is creating the API deployment,
enter:
oci api-gateway work-request-log list --work-request-id <work-request-ocid>
6. (Optional) If the work request that is creating the API deployment fails and you want to
For more information about using the CLI, see Command Line Interface (CLI). For a complete
list of flags and options available for CLI commands, see CLI Help.
When defining a route path in an API deployment specification, you can include a path
parameter to exactly replace an individual segment of the path. If necessary, you can include
multiple path parameters in the route path. You can also append the asterisk (*) wildcard to a
path parameter in the route path to provide even more flexibility when identifying requests to
send to the same backend.
The examples in this topic assume you are adding route paths to an API deployment
specification in a JSON file. Note the examples also apply when you're defining an
API deployment specification using dialogs in the Console.
You might have a requirement to route requests with similar URLs to the same backend. For
example:
l https://<gateway-hostname>/marketing/hello/us/index.html
l https://<gateway-hostname>/marketing/hello/apac/index.html
l https://<gateway-hostname>/marketing/hello/emea/index.html
To enable calls to these similar URLs to resolve to the same backend, add a path parameter
name enclosed within curly brackets as the segment of the route path that will vary between
API calls. For example, {region} as shown below:
{
"routes": [
{
"path": "/hello/{region}/index.html",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
}
}
]
}
You might have a requirement to route requests to the same backend, even though the
request URLs are significantly different. For example:
l https://<gateway-hostname>/marketing/hello/us/index.html
l https://<gateway-hostname>/marketing/hello/apac/introduction/
l https://<gateway-hostname>/marketing/hello/emea/welcome.html
l https://<gateway-hostname>/marketing/hello/introduction
l https://<gateway-hostname>/marketing/hello/top.html
l https://<gateway-hostname>/marketing/hello/
To enable calls to these significantly different URLs to resolve to the same backend:
l add a path parameter name enclosed within curly brackets as the first segment of the
route path that will differ between the various API calls
l add the asterisk (*) wildcard to the end of the path parameter name
Note that a path parameter name with an asterisk wildcard will match:
l no path segment
l a single path segment
l multiple path segments
To enable you to use parameters included in API calls, the API Gateway service saves the
values of the following types of parameter in temporary 'context tables':
l Path parameters you define in the API deployment specification (see Adding Path
Parameters and Wildcards to Route Paths) are saved in records in the request.path
table.
l Query parameters included in the call to the API are saved in records in the
request.query table.
l Header parameters included in the call to the API are saved in records in the
request.headers table.
l Authentication parameters returned by an authorizer function or contained in a JSON
Web Token (JWT) are saved in records in the request.auth table (see Using Authorizer
Functions to Add Authentication and Authorization to API Deployments and Using JSON
Web Tokens (JWTs) to Add Authentication and Authorization to API Deployments
respectively).
When defining request and response policies, and HTTP and HTTPS back ends, you can
reference the value of a parameter in a context table using a 'context variable'. A context
variable has the format <context-table-name>[<key>] where:
If you want to include the context variable within a string in the API deployment specification
(for example, in the url property of an HTTP back end definition), use the format ${<context-
table-name>[<key>]}.
For example, the request.path[region] context variable in the example below returns the
value of the record identified by the region key in the request.path context table.
{
"routes": [
{
"path": "/weather/{region}",
"methods": ["GET"],
"backend": {
"type": "HTTP_BACKEND",
"url": "https://api.weather.gov/${request.path[region]}"
}
}
]
}
l A single record is created in the context table for each discrete parameter in an HTTP
request. If the HTTP request includes two (or more) parameters of the same type and
with the same name, the value of each parameter with that name is saved in the same
record in the context table and identified by the same key. However, only the first value
in the context table record can be substituted in place of a context variable. When
adding a context variable for which multiple values can exist in the context table record
and you want the first value in the context table record to be substituted in place of the
context variable, add the context variable to the API deployment specification in the
format ${<context-table-name>[<key>]}
l If a parameter value includes special characters that have been encoded, the encoding
is preserved when the value is saved in the context table. When the value is substituted
for a context variable, the encoded value is substituted in place of the context variable.
For example, if San José is included in a query parameter as San+José, the
encoded version is what will be substituted in place of the context variable for that
query parameter.
l If a context variable key does not exist in the specified context table, an empty string is
substituted in place of the context variable.
l If a context variable key contains a dot, the dot is treated as any other character. It is
not treated as an indicator of a parent-child relationship between the strings either side
of it.
l If a path parameter includes a wildcard (for example, generic_welcome*), the path
parameter without the wildcard is used as the key.
l You can include a context variable as a path segment in the URL property of an
HTTP back end definition, but not as a query parameter. For example:
o You can use the request.query[state] context variable as a path segment in the
URL property, as shown in the following valid HTTP back end definition:
{
"path": "/weather/{region}",
"methods": ["GET"],
"backend": {
"type": "HTTP_BACKEND",
"url": "https://api.weather.gov/${request.path[region]}/${request.query[state]}"
}
}
Examples
The examples in this section assume the following API deployment definition and basic API
deployment specification in a JSON file:
{
"displayName": "Marketing Deployment",
"gatewayId": "ocid1.apigateway.oc1..aaaaaaaab______hga",
"compartmentId": "ocid1.compartment.oc1..aaaaaaaa7______ysq",
"pathPrefix": "/marketing",
"specification": {
"routes": [
{
"path": "/weather",
"methods": ["GET"],
"backend": {
"type": "HTTP_BACKEND",
"url": "https://api.weather.gov"
}
}
]
},
"freeformTags": {},
"definedTags": {}
}
Note the examples also apply when you're defining an API deployment specification using
dialogs in the Console.
You can define a path parameter in the API deployment specification, and then use it
elsewhere in the API deployment specification as a context variable.
This example creates a path parameter, region, and uses it in a context variable
request.path[region] in the HTTP back end definition.
{
"path": "/weather/{region}",
"methods": ["GET"],
"backend": {
"type": "HTTP_BACKEND",
"url": "https://api.weather.gov/${request.path[region]}"
}
}
You can include different types of context variable in the same definition in the API
deployment specification.
{
"path": "/weather/{region}",
"methods": ["GET"],
"backend": {
"type": "HTTP_BACKEND",
"url": "https://api.weather.gov/${request.path[region]}/${request.query[state]}"
}
}
Example 3: Multiple context variables of the same type in the same definition
You can include the same type of context variable multiple times in the same definition.
{
"path": "/weather/{region}",
"methods": ["GET"],
"backend": {
"type": "HTTP_BACKEND",
"url": "https://api.weather.gov/${request.path[region]}/${request.query
[state]}/${request.query[city]}"
}
}
It is often valid for an HTTP request to include the same query parameter multiple times. The
API Gateway service saves the value of each parameter with the same name to the same
record in the context table. However, in the API deployment specification, it's typically the
case that only a single value can be substituted for a context variable. In these situations, you
can indicate that only the first value recorded in the context table for a key is substituted in
place of a context variable by enclosing the context variable within ${...}.
{
"path": "/weather/{region}",
"methods": ["GET"],
"backend": {
"type": "HTTP_BACKEND",
"url": "https://api.weather.gov/${request.path[region]}/${request.query
[state]}/${request.query[city]}"
}
}
If an HTTP request includes special characters (for example, the character é, the space
character) that have been encoded, the value is stored in the context table in its encoded
form. When the value from the context table is substituted for a context variable, the
encoding is preserved.
{
"path": "/weather/{region}",
"methods": ["GET"],
"backend": {
"type": "HTTP_BACKEND",
"url": "https://api.weather.gov/${request.path[region]}/${request.query
[state]}/${request.query[city]}"
}
}
You can include values passed in the headers of a request as context variables in a definition.
If the request includes a header, the value of the header is stored in the request.headers
table, and the name of the header is used as the key.
{
"path": "/weather/{region}",
"methods": ["GET"],
"backend": {
"type": "HTTP_BACKEND",
"url": "https://api.weather.gov/${request.path[region]}/${request.headers[X-Api-Key]}"
}
}
You can include values returned from an authorizer function or contained in a JWT token as
context variables in a definition:
This example uses the key-value pair returned by an authorizer function as the authentication
parameter context variable request.auth[region] in the HTTP back end definition.
{
"requestPolicies": {
"authentication": {
"type": "CUSTOM_AUTHENTICATION",
"isAnonymousAccessAllowed": false,
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq",
"tokenHeader": "Authorization"
}
},
"routes": [
{
"path": "/weather",
"methods": ["GET"],
"backend": {
"type": "HTTP_BACKEND",
"url": "https://api.weather.gov/${request.auth[region]}"
},
"requestPolicies": {
"authorization": {
"type": "ANY_OF",
"allowedScope": [ "weatherwatcher" ]
}
}
}
]
}
authorizer function identifies that jdoe is associated with the west region. The authorizer
function returns jdoe's access scope to the API Gateway service, along with the region
associated with jdoe. The API Gateway service saves the region associated with jdoe as an
authentication parameter. The HTTP back end definition specifies that callers with the
"weatherwatcher" access scope are allowed to access the HTTP back end. The API Gateway
service uses the value of the authentication parameter context variable request.auth
[region] in the request. The request resolves to https://api.weather.gov/west.
Tip
Using curl
To call an API deployed on an API gateway:
1. Open a terminal window and type a cURL command similar to the following that is
appropriate for the deployed API:
curl -k -X <method> https://<gateway-hostname>/<deployment-path-prefix>/<api-route-path>
where:
l <method> is a valid method for the deployed API (for example, GET, PUT).
l <gateway-hostname> is an automatically generated domain name in the format
<gateway-identifier>.apigateway.<region-identifier>.oci.customer-
oci.com, where:
o <gateway-identifier> is the string of characters that identifies the API
gateway. For example, lak...sjd (abbreviated for readability).
o <region-identifier> is the identifier of the region in which the
API gateway has been created. See Availability by Region.
For example, lak...sjd.apigateway.us-phoenix-1.oci.customer-oci.com.
Use the Console or the API to find out the domain name to use as the value of
<gateway-hostname>.
l /<deployment-path-prefix> is the prefix added to the path of every route in the
API deployment. Note that the deployment path prefix in the request:
o can contain multiple forward slashes (provided they are not adjacent)
o can include alphanumeric uppercase and lowercase characters
o can include the special characters $ - _ . + ! * ' ( ) , % ; : @ & =
o cannot include parameters and wildcards
o must match exactly the deployment path prefix defined for the API
deployment (see Deploying an API on an API Gateway by Creating an
API Deployment)
Use the Console or the API to find out the path prefix to use as the value of
<deployment-path-prefix>.
l /<api-route-path> is the path to a particular route defined in the API
deployment specification. Note that the route path in the request:
o is relative to the deployment path prefix
o can be a single forward slash
o can contain multiple forward slashes (provided they are not adjacent), and
can end with a forward slash
If the API gateway back end is a serverless function that accepts parameters, include
those parameters in the call to the API. For example:
curl -k -X POST https://lak...sjd.apigateway.us-phoenix-1.oci.customer-oci.com/marketing/hello/ -
d "name=john"
1. In the Console, open the navigation menu. Under Solutions and Platform, go to
Developer Services and click API Gateway.
2. Choose a Compartment you have permission to work in.
3. To see a list of all existing API gateways in the current region and compartment
(including their OCIDs), use the Gateways page.
4. To see more detail about an individual API gateway, click the name of the API gateway
on the Gateways page to show the Gateway Details page.
5. To see a list of API deployments on an API gateway (including their endpoint, state, and
OCID), click the name of the API gateway on the Gateways page and select
Deployments from the Resources list.
1. Configure your client environment to use the CLI (Configuring Your Client Environment
to use the CLI for API Gateway Development).
2. To list all the API gateways in a compartment, open a command prompt and run oci
api-gateway gateway list to list the API gateways:
oci api-gateway gateway list --compartment-id <compartment-ocid>
where:
l <compartment-ocid> is the OCID of the compartment containing the API
gateway.
For example:
oci api-gateway gateway list --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq
If you want to list just those API gateways with a status of Active, include the --
lifecycle-state ACTIVE parameter in the request. For example:
oci api-gateway gateway list --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --
lifecycle-state ACTIVE
3. To list all the API deployments in a compartment, open a command prompt and run oci
api-gateway deployment list to list the API deployments:
oci api-gateway deployment list --compartment-id <compartment-ocid>
where:
If you want to list just those API deployments with a status of Active, include the --
lifecycle-state ACTIVE parameter in the request. For example:
oci api-gateway deployment list --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --
lifecycle-state ACTIVE
For more information about using the CLI, see Command Line Interface (CLI). For a complete
list of flags and options available for CLI commands, see CLI Help.
Use the:
gateway's name or the tags applied to it, or to change an API deployment specification to add
additional back ends to the API deployment.
Note that there are some properties of API gateways and API deployments for which you
cannot change the original values.
You can update API gateways and API deployments using the Console, the CLI, and the API.
1. In the Console, open the navigation menu. Under Solutions and Platform, go to
Developer Services and click API Gateway.
2. Choose a Compartment you have permission to work in.
3. On the Gateways page, click the name of the API gateway that you want to update (or
that contains the API deployment you want to update) to show the Gateway Details
page.
4. To update an API gateway:
l Click Edit to change the API gateway's name.
l Click Move Resource to move the API gateway to a different compartment.
l Click Add Tag(s) and View Tag(s) to change and view the tags applied to the
API gateway.
5. To update an API deployment, on the Gateway Details page, select Deployments
from the Resources list and click the Actions icon (three dots) beside the API
deployment you want to update:
l Click Edit to change the API deployment's name, or to replace the original API
deployment specification. You can change the original API deployment
1. Configure your client environment to use the CLI (Configuring Your Client Environment
to use the CLI for API Gateway Development).
2. To update an existing API gateway:
a. Open a command prompt and run oci api-gateway gateway update to update
the API gateway:
oci api-gateway gateway update --gateway-id <gateway-ocid> --<property-to-update>
<property-value>
where:
l <gateway-ocid> is the OCID of the API gateway to update. To find out the
API gateway's OCID, see Listing API Gateways and API Deployments.
l <property-to-update> is the property to update. Note that you can only
change the values for display-name, freeform-tags and defined-tags.
All other values must be identical to values in the original gateway
definition.
l <property-value> is the new value of the property you want to change.
For example:
oci api-gateway gateway update --gateway-id ocid1.apigateway.oc1..aaaaaaaab______hga --
display-name "Hello World Gateway - version 2"
For example:
oci api-gateway gateway update --gateway-id ocid1.apigateway.oc1..aaaaaaaab______hga --
display-name "Hello World Gateway - version 2" --wait-for-state ACTIVE
b. (Optional) To see the status of the work request that is updating the API gateway,
enter:
oci api-gateway work-request get --work-request-id <work-request-ocid>
c. (Optional) To view the logs of the work request that is updating the API gateway,
enter:
oci api-gateway work-request-log list --work-request-id <work-request-ocid>
d. (Optional) If the work request that is updating the API gateway fails and you want
to review the error logs, enter:
oci api-gateway work-request-error --work-request-id <work-request-ocid>
e. (Optional) To verify that the API gateway has been updated, enter the following
command and confirm that the API gateway's properties are as you expect:
oci api-gateway gateway get --gateway-id <gateway-ocid>
where:
l <deployment-ocid> is the OCID of the API deployment to update. To find
out the API deployment's OCID, see Listing API Gateways and API
Deployments.
l <filename> is the relative location and filename of the JSON file containing
the replacement API deployment specification. For example, replacement-
specification.json. For more information about defining API deployment
specifications, see Creating an API Deployment Specification.
For example:
oci api-gateway deployment update --deployment-id ocid1.apideployment.oc1..aaaaaaaaab_____
_pwa --specification file:///Users/jdoe/work/replacement-specification.json
For example:
oci api-gateway deployment update --deployment-id ocid1.apideployment.oc1..aaaaaaaaab_____
_pwa --specification file:///Users/jdoe/work/replacement-specification.json --wait-for-
state ACTIVE
b. (Optional) To see the status of the work request that is updating the
API deployment, enter:
oci api-gateway work-request get --work-request-id <work-request-ocid>
c. (Optional) To view the logs of the work request that is updating the
API deployment, enter:
oci api-gateway work-request-log list --work-request-id <work-request-ocid>
d. (Optional) If the work request that is updating the API deployment fails and you
want to review the error logs, enter:
oci api-gateway work-request-error --work-request-id <work-request-ocid>
e. (Optional) To verify that the API deployment has been updated, enter the
following command and confirm that the API deployment's properties are as you
expect:
oci api-gateway deployment get --deployment-id <deployment-ocid>
For more information about using the CLI, see Command Line Interface (CLI). For a complete
list of flags and options available for CLI commands, see CLI Help.
Use the:
Note that calls to an API deployment will be disrupted while the API deployment (or the API
gateway on which it is deployed) is being moved to a different compartment. Do not call the
API deployment until the move operation is complete.
1. In the Console, open the navigation menu. Under Solutions and Platform, go to
Developer Services and click API Gateway.
2. Choose a Compartment you have permission to work in.
3. On the Gateways page, click the name of the API gateway that you want to move (or
that contains the API deployment you want to move) to show the Gateway Details
page.
4. On the Gateway Details page:
l To move the API gateway, click Move Resource, select the compartment to
which you want to move the API gateway, and click Move Resource to start the
process of moving the API gateway. Note that API deployments on the API
gateway are not moved to the new compartment.
l To move an API deployment, select Deployments from the Resources list, click
Move Resource, select the compartment to which you want to move the API
deployment, and click Move Resource to start the process of moving the API
deployment.
Do not call an API deployment while the API deployment (or the API gateway on which it
is deployed) is in the process of being moved to the new compartment.
5. On the Gateway Details page, select Work Requests from the Resources list and
confirm the move operation is complete.
When the move operation is complete, resume calls to the API deployment.
1. Configure your client environment to use the CLI (Configuring Your Client Environment
to use the CLI for API Gateway Development).
2. To move an API gateway to a different compartment:
a. Open a command prompt and run oci api-gateway gateway change-
compartment to move the API gateway:
oci api-gateway gateway change-compartment --gateway-id <gateway-ocid> --compartment-id
<compartment-ocid>
where:
l <gateway-ocid> is the OCID of the API gateway to move. To find out the
API gateway's OCID, see Listing API Gateways and API Deployments.
l <compartment-ocid> is the OCID of the compartment to which to move the
API gateway.
For example:
oci api-gateway gateway change-compartment --gateway-id ocid1.apigateway.oc1..aaaaaaaab___
___hga --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq
For example:
oci api-gateway gateway change-compartment --gateway-id ocid1.apigateway.oc1..aaaaaaaab___
___hga --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq" --wait-for-state ACTIVE
b. (Optional) To see the status of the work request that is moving the API gateway,
enter:
oci api-gateway work-request get --work-request-id <work-request-ocid>
c. (Optional) To view the logs of the work request that is moving the API gateway,
enter:
oci api-gateway work-request-log list --work-request-id <work-request-ocid>
d. (Optional) If the work request that is moving the API gateway fails and you want
to review the error logs, enter:
oci api-gateway work-request-error --work-request-id <work-request-ocid>
e. (Optional) To verify that the API gateway has been moved, enter the following
command and confirm that the API gateway's new compartment OCID is as you
expect:
oci api-gateway gateway get --gateway-id <gateway-ocid>
where:
l <deployment-ocid> is the OCID of the API deployment to move. To find out
the API deployment's OCID, see Listing API Gateways and API
Deployments.
l <compartment-ocid> is the OCID of the compartment to which to move the
API deployment.
For example:
For example:
oci api-gateway deployment change-compartment --deployment-id
ocid1.apideployment.oc1..aaaaaaaaab______pwa --compartment-id
ocid1.compartment.oc1..aaaaaaaa7______ysq --wait-for-state ACTIVE
b. (Optional) To see the status of the work request that is moving the
API deployment, enter:
oci api-gateway work-request get --work-request-id <work-request-ocid>
c. (Optional) To view the logs of the work request that is moving the
API deployment, enter:
oci api-gateway work-request-log list --work-request-id <work-request-ocid>
d. (Optional) If the work request that is moving the API deployment fails and you
want to review the error logs, enter:
oci api-gateway work-request-error --work-request-id <work-request-ocid>
e. (Optional) To verify that the API deployment has been moved, enter the following
command and confirm that the API deployment's new compartment OCID is as
you expect:
For more information about using the CLI, see Command Line Interface (CLI). For a complete
list of flags and options available for CLI commands, see CLI Help.
Use the:
You can delete an API gateway from the API Gateway service, provided there are no API
deployments on it.
You can delete individual API deployments on an API gateway, one at a time. Note that when
you delete an API deployment, its API deployment specification is permanently removed.
Note that deleted API gateways and API deployments continue to be shown in the Console for
90 days, with a status of Deleted. After 90 days, deleted API gateways and API deployments
are no longer shown.
1. In the Console, open the navigation menu. Under Solutions and Platform, go to
Developer Services and click API Gateway.
2. Choose a Compartment you have permission to work in.
3. On the Gateways page, click the name of the API gateway that you want to delete (or
that contains the API deployment you want to delete) to show the Gateway Details
page.
4. On the Gateway Details page:
l To delete the API gateway, click Delete below the API gateway's name. The
API gateway is permanently removed. Note that you cannot delete an API
gateway if it still has API deployments on it. You must delete the API deployments
first.
l To delete an API deployment, select Deployments from the Resources list,
click the Actions icon (three dots) beside the API deployment you want to delete,
and select Delete. The API deployment and its API deployment specification are
permanently removed.
1. Configure your client environment to use the CLI (Configuring Your Client Environment
to use the CLI for API Gateway Development).
2. To delete an existing API gateway:
a. Open a command prompt and run oci api-gateway gateway delete to delete
the API gateway:
oci api-gateway gateway delete --gateway-id <gateway-ocid>
where:
l <gateway-ocid> is the OCID of the API gateway to delete. To find out the
API gateway's OCID, see Listing API Gateways and API Deployments.
For example:
Note that you cannot delete an API gateway if it still has API deployments on it
(including API deployments that are in different compartments to the API gateway
itself). You must delete the API deployments first.
The response to the command includes:
l The lifecycle state (for example, DELETED, FAILED).
l The id of the work request to delete the API gateway (details of work
requests are available for seven days after completion, cancellation, or
failure).
If you want the command to wait to return control until the API gateway has been
deleted (or the request has failed), include either or both the following
parameters:
l --wait-for-state DELETED
l --wait-for-state FAILED
For example:
oci api-gateway gateway delete --gateway-id ocid1.apigateway.oc1..aaaaaaaab______hga --
wait-for-state DELETED
b. (Optional) To see the status of the work request that is deleting the API gateway,
enter:
oci api-gateway work-request get --work-request-id <work-request-ocid>
c. (Optional) To view the logs of the work request that is deleting the API gateway,
enter:
oci api-gateway work-request-log list --work-request-id <work-request-ocid>
d. (Optional) If the work request that is deleting the API gateway fails and you want
to review the error logs, enter:
oci api-gateway work-request-error --work-request-id <work-request-ocid>
e. (Optional) To verify that the API gateway has been deleted, enter the following
command and confirm that the API gateway's lifecycle state is DELETED:
where:
l <deployment-ocid> is the OCID of the API deployment to delete. To find
out the API deployment's OCID, see Listing API Gateways and API
Deployments.
For example:
oci api-gateway deployment delete --deployment-id ocid1.apideployment.oc1..aaaaaaaaab_____
_pwa
For example:
oci api-gateway deployment delete --deployment-id ocid1.apideployment.oc1..aaaaaaaaab_____
_pwa --wait-for-state DELETED
b. (Optional) To see the status of the work request that is deleting the
API deployment, enter:
oci api-gateway work-request get --work-request-id <work-request-ocid>
c. (Optional) To view the logs of the work request that is deleting the
API deployment, enter:
oci api-gateway work-request-log list --work-request-id <work-request-ocid>
d. (Optional) If the work request that is deleting the API deployment fails and you
want to review the error logs, enter:
oci api-gateway work-request-error --work-request-id <work-request-ocid>
e. (Optional) To verify that the API deployment has been deleted, enter the
following command and confirm that the API deployment 's lifecycle state is
DELETED:
oci api-gateway deployment get --deployment-id <deployment-ocid>
For more information about using the CLI, see Command Line Interface (CLI). For a complete
list of flags and options available for CLI commands, see CLI Help.
Use the:
The API Gateway service stores logs in Oracle Cloud Infrastructure. Note that until an Oracle
Cloud Infrastructure logging service is released, the API Gateway service stores logs as files
in a storage bucket in Oracle Cloud Infrastructure Object Storage. Each log file contains the
log messages output in a ten minute logging window. Log files are available in Object Storage
approximately ten minutes after the end of the logging window.
You can set logging policies globally for all routes in the API deployment specification, and
also set different logging policies for individual routes to override the global policy.
1. Create or update an API deployment using the Console, select the From Scratch
option, and enter details on the Basic Information page.
For more information, see Deploying an API on an API Gateway by Creating an
API Deployment and Updating API Gateways and API Deployments.
2. In the API Logging Policies section of the Basic Information page, specify:
l Access Log: Whether to record a summary of every request and response that
goes through the API gateway. By default, this option is not selected.
l Execution Log: Whether to record information about processing within the API
gateway. By default, this option is not selected. If you select this option, specify a
Log Level as one of the following:
o Information, to record a summary of every processing stage.
o Warning, to record only transient errors that occur during processing. For
example, a connection reset.
o Error, to record only persistent errors that occur during processing. For
example, an internal error, or a call to a function that returns a 404
message.
3. Click Next to enter details for individual routes in the API deployment on the Routes
page. To specify logging policies that apply to an individual route, click Show Logging
Policies and specify:
l Access Log: Whether to record a summary of every request and response that
goes through the API gateway for an individual route. By default, this option is not
selected.
l Execution Log: Whether to record information about processing within the API
gateway for an individual route. By default, this option is not selected. If you
select this option, specify a Log Level as one of the following:
o Information, to record a summary of every processing stage.
o Warning, to record only transient errors that occur during processing. For
example, a connection reset.
o Error, to record only persistent errors that occur during processing. For
example, an internal error, or a call to a function that returns a 404
message.
4. Click Next to review the details you entered for the API deployment.
5. Click Create or Save Changes to create or update the API deployment.
6. (Optional) Confirm the API has been deployed successfully by calling it (see Calling an
API Deployed on an API Gateway).
1. Using your preferred JSON editor, edit the existing API deployment specification to
which you want to add a logging policy, or create a new API deployment specification
(see Creating an API Deployment Specification).
2. (Optional) To add a logging policy to the API deployment specification that applies
globally to all routes in the API deployment specification:
a. Insert a loggingPolicies section before the routes section. For example:
{
"loggingPolicies": {},
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
}
}
]
}
b. (Optional) Record a summary of every request and response that goes through
the gateway by including the accessLog policy in the loggingPolicies section,
and setting the isEnabled property to true.
For example:
{
"loggingPolicies": {
"accessLog": {
"isEnabled": true
},
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
}
}
]
}
{
"loggingPolicies": {
"accessLog": {
"isEnabled": true
},
"executionLog": {
"isEnabled": true,
"logLevel": "INFO"
}
},
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
}
}
]
}
3. (Optional) To add a logging policy to the API deployment specification that applies to a
particular route (overriding the global logging policy):
a. Insert a loggingPolicies section after the route's backend section. For
example:
{
"loggingPolicies": {
"accessLog": {
"isEnabled": true
},
"executionLog": {
"isEnabled": true,
"logLevel": "INFO"
}
},
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
},
"loggingPolicies": {}
}
]
}
b. (Optional) Record a summary of every request and response that goes through
the gateway to the route by including the accessLog policy in the
loggingPolicies section, and setting the isEnabled property to true.
For example:
{
"loggingPolicies": {
"accessLog": {
"isEnabled": true
},
"executionLog": {
"isEnabled": true,
"logLevel": "INFO"
}
},
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
},
"loggingPolicies": {
"accessLog": {
"isEnabled": true
}
}
}
]
}
c. (Optional) Record information about processing within the API gateway for the
route by including the executionLog policy in the loggingPolicies section,
setting the isEnabled property to true, and setting the logLevel property to one
of the following:
l INFO to record a summary of every processing stage.
l WARN to record only transient errors that occur during processing. For
example, a connection reset.
l ERROR to record only persistent errors that occur during processing. For
example, an internal error, or a call to a function that returns a 404
message.
For example:
{
"loggingPolicies": {
"accessLog": {
"isEnabled": true
},
"executionLog": {
"isEnabled": true,
"logLevel": "INFO"
}
},
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
},
"loggingPolicies": {
"accessLog": {
"isEnabled": true
},
"executionLog": {
"isEnabled": true,
"logLevel": "ERROR"
}
}
}
]
}
Viewing Logs
Having added logging policies to an API deployment specification and deployed the API on an
API gateway, the API Gateway service writes logs accordingly.
To view logs that have been stored in a storage bucket in Oracle Cloud Infrastructure Object
Storage:
where:
l <deployment-ocid> is the OCID of the API deployment.
l <datetimestamp> is the date and time at the start of the logging window.
5. Click the Actions icon (three dots) beside the log file you want to view, and then click
Download and save the log file in a convenient location.
6. Open the log file in a text editor to view the log messages.
Each log message contains:
l the number of bytes sent in the message
l the compartment OCID
l the API deployment OCID
l the API gateway OCID
l the user agent
l the request and the endpoint
l the client IP address
l the request duration (in seconds)
l the message number
l the timestamp
For example:
{"bodybytesSent":292,"compartmentId":"ocid1.compartment.oc1..aaaaaaaa7______
ysq","deploymentId":"ocid1.apideployment.oc1.phx.aaaaaaaaab______
pwa","gatewayId":"ocid1.apigateway.oc1.phxaaaaaaaa7______
ysq","httpReferrer":"","httpUserAgent":"curl/7.54.0","msg":"GET /marketing/hello
HTTP/1.1","remoteAddr":"123.45.678.90","remoteUser":"","requestDuration":"0.167","requestId":"0d5
afahl6lkje4rto9tqp896004","status":200,"ts":1560954177210}
Having used the API Gateway service to create an API gateway, you can create an
API deployment to access HTTP and HTTPS URLs.
The HTTP or HTTPS URL that you specify for the back-end service can be:
The URL you provide in the API deployment specification to identify the HTTP or HTTPS back-
end service can include the host name or the host IP address. If you provide the host name,
use the DHCP Options property of the API gateway's subnet to control how host names
included in the API deployment specification are resolved to IP addresses at runtime:
l If the host name for a back-end service is publicly published on the internet, or if the
host name belongs to an instance in the same VCN, select a DHCP options set for the
API gateway's subnet that has the Oracle-provided Internet and VCN Resolver as the
DNS Type. This is the default if you do not explicitly select a DHCP options set.
l If the host name is for a back-end service on your own private or internal network,
select a DHCP options set for the API gateway's subnet that has Custom Resolver as the
DNS Type, and has the URL of a suitable DNS server that can resolve the host name to
an IP address.
Note that you can change the DNS server details in the DHCP options set specified for an API
gateway's subnet. The API gateway will be reconfigured to use the updated DNS server details
within two hours. For more information about resolving host names to IP addresses, see DNS
in Your Virtual Cloud Network and DHCP Options.
You can add HTTP and HTTPS back ends to an API deployment specification by:
1. Create or update an API deployment using the Console, select the From Scratch
option, and enter details on the Basic Information page.
For more information, see Deploying an API on an API Gateway by Creating an
API Deployment and Updating API Gateways and API Deployments.
2. On the Routes page, create a new route and specify:
l Path: A path for API calls using the listed methods to the back-end service. Note
that the route path you specify:
o is relative to the deployment path prefix (see Deploying an API on an API
Gateway by Creating an API Deployment)
o must be preceded by a forward slash ( / ), and can be just that single
forward slash
o can contain multiple forward slashes (provided they are not adjacent), and
can end with a forward slash
o can include alphanumeric uppercase and lowercase characters
o can include the special characters $ - _ . + ! * ' ( ) , % ; : @ & =
o can include parameters and wildcards (see Adding Path Parameters and
Wildcards to Route Paths)
l Methods: One or more methods accepted by the back-end service. For example,
GET, PUT.
l Type: The type of the back-end service as HTTP.
l URL: The URL you want to use as the back-end service, in the format
<protocol>://<host>:<port>/<path> where:
o <protocol> is either http or https.
o <host> is the host name or the host IP address of the back-end service. For
example, api.weather.gov. If you provide a host name, use the DHCP
Options property of the API gateway's subnet to control how host names are
resolved to IP addresses at runtime.
o <port> is optionally a port number.
o <path> is optionally a subdirectory or file at the host where the back-end
service is located.
Note that <path> must not contain parameters directly, but can contain
context variables. For more information and examples showing how to use
context variables to substitute path, query, and header parameters into the
path, see Adding Context Variables to Policies and HTTP Back End
Definitions.
For example, "url": "https://api.weather.gov".
l Connection establishment timeout in seconds: Optionally, a floating point
value indicating how long (in seconds) to allow when establishing a connection
with the back-end service. The minimum is 1.0, the maximum is 75.0. If not
specified, the default of 60.0 seconds is used.
l Request transmit timeout in seconds: Optionally, a floating point value
indicating how long (in seconds) to allow when transmitting a request to the back-
end service. The minimum is 1.0, the maximum is 300.0. If not specified, the
default of 10.0 seconds is used.
l Reading response timeout in seconds: Optionally, a floating point value
indicating how long (in seconds) to allow when reading a response from the back-
end service. The minimum is 1.0, the maximum is 300.0. If not specified, the
default of 10.0 seconds is used.
l Disable SSL verification: Whether to disable SSL verification when
communicating with the back-end service. By default, this option is not selected.
In this example, the route defines a weather service as an HTTP back end.
Field: Enter:
Path: /weather
Methods: GET
Type: HTTP
URL: https://api.weather.gov
1. Using your preferred JSON editor, create a new API deployment specification (see
Creating an API Deployment Specification) in the format:
{
"requestPolicies": {},
"routes": [
{
"path": "<api-route-path>",
"methods": ["<method-list>"],
"backend": {
"type": "HTTP_BACKEND",
"url": "<identifier>",
"connectTimeoutInSeconds": <seconds>,
"readTimeoutInSeconds": <seconds>,
"sendTimeoutInSeconds": <seconds>,
"isSSLVerifyDisabled": <true|false>
},
"requestPolicies": {},
}
]
}
where:
l "requestPolicies" specifies optional policies to control the behavior of an API
deployment. If you want to apply policies to all routes in an API deployment
specification, place the policies outside the routes section. If you want to apply
the policies just to a particular route, place the policies inside the routes section.
See Adding Request Policies and Response Policies to API Deployment
Specifications.
l <api-route-path> specifies a path for API calls using the listed methods to the
back-end service. Note that the route path you specify:
o is relative to the deployment path prefix (see Deploying an API on an API
Gateway by Creating an API Deployment)
o must be preceded by a forward slash ( / ), and can be just that single
forward slash
o can contain multiple forward slashes (provided they are not adjacent), and
can end with a forward slash
o can include alphanumeric uppercase and lowercase characters
end service. The minimum is 0.0, the maximum is 300.0. If not specified, the
default of 10.0 seconds is used.
l "sendTimeoutInSeconds": <seconds> is an optional floating point value
indicating how long (in seconds) to allow when transmitting a request to the back-
end service. The minimum is 0.0, the maximum is 300.0. If not specified, the
default of 10.0 seconds is used.
l "isSSLVerifyDisabled": <true|false> is an optional boolean value (either
true or false) indicating whether to disable SSL verification when
communicating with the back-end service. If not specified, the default of false is
used.
For example, the following basic API deployment specification defines a weather
service as an HTTP back end:
{
"routes": [
{
"path": "/weather",
"methods": ["GET"],
"backend": {
"type": "HTTP_BACKEND",
"url": "https://api.weather.gov",
"connectTimeoutInSeconds": 45,
"readTimeoutInSeconds": 15,
"sendTimeoutInSeconds": 15,
"isSSLVerifyDisabled": false
}
}
]
}
Oracle Functions enables you to create serverless functions that are built as Docker images
and pushed to a specified Docker registry. A definition of each function is stored as metadata
in the Oracle Functions server. When a function is invoked for the first time, Oracle Functions
pulls the function's Docker image from the specified Docker registry, runs it as a Docker
container, and executes the function. If there are subsequent requests to the same function,
Oracle Functions directs those requests to the same running container. After a period being
idle, the Docker container is stopped.
Having used the API Gateway service to create an API gateway, you can create an
API deployment that invokes serverless functions defined in Oracle Functions.
Before you can use serverless functions in Oracle Functions as the back end for an API:
l Serverless functions referenced in the API deployment specification must have already
been created and deployed in Oracle Functions (see Creating and Deploying Functions).
The functions must be routable from the VCN specified for the API gateway, either
through an internet gateway (in the case of a public API gateway) or through a service
gateway (in the case of a private API gateway).
l Appropriate policies must already exist that give access to serverless functions defined
in Oracle Functions to:
o a group to which your user account belongs (see Create a Policy to Give API
You can add serverless function back ends to an API deployment specification by:
l Confirm that you have completed the prerequisite steps for using Oracle Functions, as
described in Preparing for Oracle Functions.
l Create and deploy the function in a compartment to which API gateways have been
granted access, as described in Creating and Deploying Functions.
1. Create or update an API deployment using the Console, select the From Scratch
option, and enter details on the Basic Information page.
For more information, see Deploying an API on an API Gateway by Creating an
API Deployment and Updating API Gateways and API Deployments.
2. On the Routes page, create a new route and specify:
l Path: A path for API calls using the listed methods to the back-end service. Note
that the route path you specify:
Field: Enter:
Path: /hello
Methods: GET
1. Using your preferred JSON editor, create the API deployment specification in a JSON file
in the format:
{
"requestPolicies": {},
"routes": [
{
"path": "<api-route-path>",
"methods": ["<method-list>"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "<identifier>"
},
"requestPolicies": {}
}
]
}
where:
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
}
}
]
}
Equally, there are some situations in a production deployment where you'll want a particular
path for a route to consistently return the same stock response without sending a request to a
back end. For example, when you want a call to a path to always return a specific HTTP status
code in the response.
Using the API Gateway service, you can define a path to a stock response back end that
always returns the same:
Note the following restrictions when defining stock responses and stock response back ends:
You can add stock response back ends to an API deployment specification by:
1. Create or update an API deployment using the Console, select the From Scratch
option, and enter details on the Basic Information page.
For more information, see Deploying an API on an API Gateway by Creating an
API Deployment and Updating API Gateways and API Deployments.
2. On the Routes page, create a new route and specify:
l Path: A path for API calls using the listed methods to the back-end service. Note
that the route path you specify:
o is relative to the deployment path prefix (see Deploying an API on an API
Gateway by Creating an API Deployment)
o must be preceded by a forward slash ( / ), and can be just that single
forward slash
o can contain multiple forward slashes (provided they are not adjacent), and
can end with a forward slash
o can include alphanumeric uppercase and lowercase characters
o can include the special characters $ - _ . + ! * ' ( ) , % ; : @ & =
o can include parameters and wildcards (see Adding Path Parameters and
Wildcards to Route Paths)
l Methods: One or more methods accepted by the back-end service. For example,
GET, PUT.
l Type: The type of the back-end service as Stock Response.
l Status Code: Any valid HTTP response code. For example, 200
l Body: Optionally specifies the content of the response body, in an appropriate
format. For example:
o If you specify a Header Name and Header Value of Content-Type and
text/plain respectively, the response body might be "Hello world".
o If you specify a Header Name and Header Value of Content-Type and
application/json respectively, the response body might be
{"username": "john.doe"}.
Note that the response body must not exceed 5KB in length (including any
encoding).
l Header Name and Header Value: Optionally, you can specify the name of an
HTTP response header and its value. For example, a name of Content-Type and a
value of application/json. You can specify multiple header name and value
Field: Enter:
Path: /test
Methods: GET
In this example, a request to the /test-redirect path returns a 302 status code and a
temporary url in the Location header of the response.
Field: Enter:
Path: /test-redirect
Methods: GET
Field: Enter:
Body: n/a
1. Using your preferred JSON editor, edit the existing API deployment specification to
which you want to add a stock response back end, or create a new API deployment
specification (see Creating an API Deployment Specification).
For example, the following basic API deployment specification defines a simple Hello
World serverless function in Oracle Functions as a single back end:
{
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
}
}
]
}
2. In the routes section, include a new path section for a stock response back end:
{
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
}
},
{
"path": "<api-route-path>",
"methods": ["<method-list>"],
"backend": {
"type": "STOCK_RESPONSE_BACKEND",
"status": <http-response-code>,
"headers": [{
"name": "<header-name>",
"value": "<header-value>"
}],
"body": "<body-content>"
}
}
]
}
where:
l <api-route-path> specifies a path for API calls using the listed methods to the
stock response back end. Note that the route path you specify:
o is relative to the deployment path prefix (see Deploying an API on an API
Gateway by Creating an API Deployment)
o must be preceded by a forward slash ( / ), and can be just that single
forward slash
o can contain multiple forward slashes (provided they are not adjacent), and
can end with a forward slash
o can include alphanumeric uppercase and lowercase characters
o can include the special characters $ - _ . + ! * ' ( ) , % ; : @ & =
o can include parameters and wildcards (see Adding Path Parameters and
Wildcards to Route Paths)
l <method-list> specifies one or more methods accepted by the stock response
back end, separated by commas. For example, "GET, PUT".
l "type": "STOCK_RESPONSE_BACKEND" indicates that the API gateway itself will
act as the back end and return the stock response you define (the status code, the
header fields and the body content).
l <http-response-code> is any valid HTTP response code. For example, 200
l "name": "<header-name>", "value": "<header-value>" optionally specifies
the name of an HTTP response header and its value. For example, "name":
"Content-Type", "value":"application/json" . You can specify multiple
"name": "<header-name>", "value": "<header-value>" pairs in the
headers: section (up to a maximum of 50). Note that in each case:
o <header-name> must not exceed 1KB in length
o <header-value> must not exceed 4KB in length
l "body": "<body-content>" optionally specifies the content of the response
body, in an appropriate format. For example:
o If the Content-Type header is text/plain, the response body might be
"body": "Hello world".
o If the Content-Type header is application/json, the response body
might be "body": "{\"username\": \"john.doe\"}". In the case of a
JSON response, note that quotation marks in the response have to be
escaped with a backslash ( \ ) character.
Note that <body-content> must not exceed 5KB in length (including any
encoding).
In this example, a request to the /test path returns a 200 status code and a JSON
payload in the body of the response.
{
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
}
},
{
"path": "/test",
"methods": ["GET"],
"backend": {
"type": "STOCK_RESPONSE_BACKEND",
"status": 200,
"headers": [{
"name": "Content-Type",
"value": "application/json"
}],
"body" : "{\"username\": \"john.doe\"}"
}
}
]
}
In this example, a request to the /test-redirect path returns a 302 status code and a
temporary url in the Location header of the response. This example also demonstrates
that you can create an API deployment specification with just one route to a back end of
type STOCK_RESPONSE_BACKEND.
{
"routes": [
{
"path": "/test-redirect",
"methods": ["GET"],
"backend": {
"type": "STOCK_RESPONSE_BACKEND",
"status": 302,
"headers": [{
"name": "Location",
"value": "http://www.example.com"
}]
}
}
]
}
You can add request and response policies that apply globally to all routes in an API
deployment specification, and also (in some cases) request and response policies that apply
only to particular routes.
You can add request and response policies to an API deployment specification by:
1. Create or update an API deployment using the Console, select the From Scratch
option, and enter details on the Basic Information page.
For more information, see Deploying an API on an API Gateway by Creating an
API Deployment and Updating API Gateways and API Deployments.
2. In the API Request Policies section of the Basic Information page, specify request
policies that apply globally to all routes in the API deployment specification:
l Authentication: A policy to control access to APIs you deploy to API gateways
based on the caller (a person or system) sending a request, and define what it is
that they are allowed to do. Having specified a global authentication policy first,
you can then specify authorization policies that apply to individual routes in the
API deployment specification. See Adding Authentication and Authorization to API
Deployments.
l CORS: A policy to enable CORS support in the APIs you deploy to API gateways.
You can also specify CORS policies that apply to individual routes in the API
deployment specification (you don't need to have entered a global CORS policy
first). See Adding CORS support to API Deployments.
l Rate Limiting: A policy to limit the rate at which front-end clients can make
requests to back-end services. You can only apply a rate-limiting policy globally
to all routes in the API deployment specification (not to individual routes). See
Limiting the Number of Requests to API Gateway Back Ends.
3. Click Next to enter details for individual routes in the API deployment on the Routes
page. To specify request policies that apply to an individual route, click Show Route
Request Policies and specify:
l Authorization: A policy to specify the operations a caller is allowed to perform,
based on the caller's access scopes. Note that you must have already specified a
global authentication policy before you can specify an authorization policy on an
individual route. See Adding Authentication and Authorization to API
Deployments.
l CORS: A policy to enable CORS support for individual routes in the API
deployment specification (you don't need to have entered a global CORS policy
first). See Adding CORS support to API Deployments.
4. Click Next to review the details you entered for the API deployment.
5. Click Create or Save Changes to create or update the API deployment.
6. (Optional) Confirm the API has been deployed successfully by calling it (see Calling an
API Deployed on an API Gateway).
1. Using your preferred JSON editor, edit the existing API deployment specification to
which you want to add a request policy, or create a new API deployment specification
(see Creating an API Deployment Specification).
At a minimum, the API deployment specification will include a routes section
containing:
l A path. For example, /hello
l One or more methods. For example, GET
l A definition of a back end. For example, a URL, or the OCID of a function in Oracle
Functions.
For example, the following basic API deployment specification defines a simple Hello
World serverless function in Oracle Functions as a single back end:
{
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
}
}
]
}
2. To add a request policy that applies globally to all routes in the API deployment
specification:
a. Insert a requestPolicies section before the routes section. For example:
{
"requestPolicies": {},
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
}
}
]
}
For more information about the rateLimiting request policy, see Limiting the
Number of Requests to API Gateway Back Ends.
3. To add a request policy that applies to an individual route in the API deployment
specification:
a. Insert a requestPolicies section after the route's backend section. For
example:
{
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
},
"requestPolicies": {}
}
]
}
For more information about the cors request policy, see Adding CORS support to
API Deployments.
l maintain high availability and fair use of resources by protecting back ends from being
overwhelmed by too many requests
l prevent denial-of-service attacks
l constrain costs of resource consumption
l restrict usage of APIs by your customers' users in order to monetize APIs
You apply a rate limit globally to all routes in an API deployment specification.
If a request is denied because the rate limit has been exceeded, the response header specifies
when the request can be retried.
You use a request policy to limit the number of requests (see Adding Request Policies and
Response Policies to API Deployment Specifications).
You can add a rate-limiting request policy to an API deployment specification by:
1. Create or update an API deployment using the Console, select the From Scratch
option, and enter details on the Basic Information page.
For more information, see Deploying an API on an API Gateway by Creating an
API Deployment and Updating API Gateways and API Deployments.
2. In the API Request Policies section of the Basic Information page, click the Add
button beside Rate Limiting and specify:
l Number of Requests per Second: The maximum number of requests per
second to send to any one route.
l Type of Rate Limit: How the maximum number of requests per second
threshold is applied. You can specify that the maximum applies either to the
number of requests sent from any one front-end client (identified by its IP
address), or to the total number of requests sent from all front-end clients.
3. Click Save Changes, and then click Next to enter details for individual routes in the
API deployment on the Routes page. Note that you cannot apply rate-limiting policies
to individual routes in the API deployment specification.
4. Click Next to review the details you entered for the API deployment.
5. Click Create or Save Changes to create or update the API deployment.
6. (Optional) Confirm the API has been deployed successfully by calling it (see Calling an
API Deployed on an API Gateway).
1. Using your preferred JSON editor, edit the existing API deployment specification to
which you want to add a request limit, or create a new API deployment specification
(see Creating an API Deployment Specification).
For example, the following basic API deployment specification defines a simple Hello
World serverless function in Oracle Functions as a single back end:
{
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
}
}
]
}
2. Insert a requestPolicies section before the routes section, if one doesn't exist
already. For example:
{
"requestPolicies": {},
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
}
}
]
}
3. Add the following rateLimiting policy to the new requestPolicies section to apply to
all routes defined in the specification:
{
"requestPolicies": {
"rateLimiting": {
"rateKey": "<ratekey-value>",
"rateInRequestsPerSecond": <requests-per-second>
}
},
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
}
}
]
}
where:
l <ratekey-value> specifies whether the maximum number of requests threshold
applies to the number of requests from individual front-end clients (each
identified by their IP address) or to the total number of requests sent to the back-
end service. Valid values are CLIENT_IP and TOTAL.
l <requests-per-second> is the maximum number of requests per second to send
to any route.
For example:
{
"requestPolicies": {
"rateLimiting": {
"rateKey": "CLIENT_IP",
"rateInRequestsPerSecond": 10
}
},
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
}
}
]
}
Cross-Origin Resource Sharing (CORS) is a cross-origin sharing standard to relax the same-
origin policy by allowing code on a web page to consume a REST API served from a different
origin. The CORS standard uses additional HTTP request headers and response headers to
specify the origins that can be accessed.
The CORS standard also requires that for certain HTTP request methods, the request must be
"pre-flighted". Before sending the actual request, the web browser sends a pre-flight request
to the server to determine whether the methods in the actual request are supported. The
server responds with the methods it will allow in an actual request. The web browser only
sends the actual request if the response from the server indicates that the methods in the
actual request are allowed. The CORS standard also enables servers to notify clients whether
requests can include credentials (cookies, authorization headers, or TLS client certificates).
For more information about CORS, see resources available online including those from W3C
and Mozilla.
Using the API Gateway service, you can enable CORS support in the APIs you deploy to
API gateways. When you enable CORS support in an API deployment, HTTP pre-flight requests
and actual requests to the API deployment return one or more CORS response headers to the
client. You set the CORS response header values in the API deployment specification.
You use request policies to add CORS support to APIs (see Adding Request Policies and
Response Policies to API Deployment Specifications). You can apply a CORS request policy
globally to all routes in an API deployment specification, or just to particular routes.
You can add a CORS request policy to an API deployment specification by:
1. Create or update an API deployment using the Console, select the From Scratch
option, and enter details on the Basic Information page.
For more information, see Deploying an API on an API Gateway by Creating an
API Deployment and Updating API Gateways and API Deployments.
2. In the API Request Policies section of the Basic Information page, click the Add
button beside CORS and specify:
l Allowed Origins: An origin that is allowed to access the API deployment. For
example, https://oracle.com. Click + Another Origin to enter second and
subsequent origins.
l Allowed Methods: One or more methods that are allowed in the actual request
to the API deployment. For example, GET, PUT.
l Max age in seconds: Optionally, an integer value indicating how long (in delta-
seconds) the results of a preflight request can be cached by a browser. If you
don't specify a value, the default is 0.
l Enable Allow Credentials: Whether the actual request to the route can be
made using credentials (cookies, authorization headers, or TLS client
certificates). By default, this option is not selected.
To find out how the different fields in the CORS request policy map onto different
CORS response headers, see How a CORS Request Policy Maps to a CORS Response.
4. Click Save Changes, and then click Next to review the details you entered for the API
deployment and for individual routes.
5. Click Create or Save Changes to create or update the API deployment.
6. (Optional) Confirm the API has been deployed successfully by calling it (see Calling an
API Deployed on an API Gateway).
1. Using your preferred JSON editor, edit the existing API deployment specification to
which you want to add CORS support, or create a new API deployment specification (see
Creating an API Deployment Specification).
For example, the following basic API deployment specification defines a simple Hello
World serverless function in Oracle Functions as a single back end:
{
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
}
}
]
}
2. To specify a CORS request policy that applies globally to all the routes in an
API deployment:
a. Insert a requestPolicies section before the routes section, if one doesn't exist
already. For example:
{
"requestPolicies": {},
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
}
}
]
}
b. Add the following cors policy to the new requestPolicies section to apply
globally to all the routes in an API deployment:
{
"requestPolicies": {
"cors":{
"allowedOrigins": [<list-of-origins>],
"allowedMethods": [<list-of-methods>],
"allowedHeaders": [<list-of-implicit-headers>],
"exposedHeaders": [<list-of-exposed-headers>],
"isAllowCredentialsEnabled": <true|false>,
"maxAgeInSeconds": <seconds>
}
},
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
}
}
]
}
where:
l "allowedOrigins": [<list-of-origins>] is a required comma-
separated list of origins that are allowed to access the API deployment. For
example, "allowedOrigins": ["*", "https://oracle.com"]
l "allowedMethods": [<list-of-methods>] is an optional comma-
separated list of HTTP methods that are allowed in the actual request to the
API deployment. For example, "allowedMethods": ["*", "GET"]
l "allowedHeaders": [<list-of-implicit-headers>] is an optional
comma-separated list of HTTP headers that are allowed in the actual
request to the API deployment. For example, "allowedHeaders": ["opc-
request-id", "If-Match"]
"cors":{
"allowedOrigins": ["*", "https://oracle.com"],
"allowedMethods": ["*", "GET"],
"allowedHeaders": [],
"exposedHeaders": [],
"isAllowCredentialsEnabled": false,
"maxAgeInSeconds": 3000
}
},
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
}
}
]
}
To find out how the different fields in the CORS request policy map onto different
CORS response headers, see How a CORS Request Policy Maps to a
CORS Response.
3. To specify a CORS request policy that applies to an individual route:
a. Insert a requestPolicies section after the backend section for the route to which
you want the policy to apply. For example:
{
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
},
"requestPolicies": {}
}
]
}
b. Add the following cors policy to the new requestPolicies section to apply to just
this particular route:
{
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
},
"requestPolicies": {
"cors":{
"allowedOrigins": [<list-of-origins>],
"allowedMethods": [<list-of-methods>],
"allowedHeaders": [<list-of-implicit-headers>],
"exposedHeaders": [<list-of-exposed-headers>],
"isAllowCredentialsEnabled": <true|false>,
"maxAgeInSeconds": <seconds>
}
}
}
]
}
where:
l "allowedOrigins": [<list-of-origins>] is a required comma-
separated list of origins that are allowed to access the API deployment. For
example, "allowedOrigins": ["*", "https://oracle.com"]
l "allowedMethods": [<list-of-methods>] is an optional comma-
separated list of HTTP methods that are allowed in the actual request to the
API deployment. For example, "allowedMethods": ["*", "GET"]
l "allowedHeaders": [<list-of-implicit-headers>] is an optional
comma-separated list of HTTP headers that are allowed in the actual
]
}
To find out how the different fields in the CORS request policy map onto different
CORS response headers, see How a CORS Request Policy Maps to a
CORS Response.
4. Save the JSON file containing the API deployment specification.
5. Use the API deployment specification when you create or update an API deployment in
the following ways:
l by specifying the JSON file in the Console when you select the Upload an
existing API option
l by specifying the JSON file in a request to the API Gateway REST API
For more information, see Deploying an API on an API Gateway by Creating an
API Deployment and Updating API Gateways and API Deployments.
6. (Optional) Confirm the API has been deployed successfully by calling it (see Calling an
API Deployed on an API Gateway).
l Authentication functionality to determine caller identity. Is the caller really who they
claim to be?
l Authorization functionality to determine appropriate access for a caller, and grant the
necessary permissions. What is the caller allowed to do?
You can add authentication and authorization functionality to API gateways to support:
l HTTP Basic Authentication
l API Key Authentication
l OAuth Authentication and Authorization
l Oracle Identity Cloud Service (IDCS) Authentication
You can add authentication and authorization functionality to an API gateway as follows:
l You can have the API gateway pass an access token included in a request to an
authorizer function deployed on Oracle Functions to perform validation (see Using
Authorizer Functions to Add Authentication and Authorization to API Deployments).
l You can have the API gateway itself validate a JSON Web Token (JWT) included in the
request with an identity provider (see Using JSON Web Tokens (JWTs) to Add
Authentication and Authorization to API Deployments).
l Processes request attributes to verify the identity of a caller with an identity provider.
l Determines the operations that the caller is allowed to perform.
l Returns the operations the caller is allowed to perform as a list of 'access scopes' (an
'access scope' is an arbitrary string used to determine access).
l Optionally returns a key-value pair for use by the API deployment. For example, as a
context variable for use in an HTTP back end definition (see Adding Context Variables to
Policies and HTTP Back End Definitions).
You then deploy the authorizer function to Oracle Functions. See Creating an Authorizer
Function.
Having deployed the authorizer function, you enable authentication and authorization for an
API deployment by including two different kinds of request policy in the API deployment
specification:
l An authentication request policy for the entire API deployment that specifies:
o The OCID of the authorizer function that you deployed to Oracle Functions that will
perform authentication and authorization.
o The request attributes to pass to the authorizer function.
o Whether unauthenticated callers can access routes in the API deployment.
l An authorization request policy for each route that specifies the operations a caller is
allowed to perform, based on the caller's access scopes as returned by the authorizer
function.
You can add authentication and authorization request policies to an API deployment
specification by:
Tip
Before you can enable authentication and authorization for API deployments using authorizer
functions:
l An identity provider (for example, Oracle Identity Cloud Service (IDCS), Auth0) must
have already been set up, containing access scopes for users allowed to access the
API deployment. See the identity provider documentation for more information (for
example, the Oracle Identity Cloud Service (IDCS) documentation, the Auth0
documentation).
l An authorizer function must have been deployed to Oracle Functions already, and an
appropriate policy must give API gateways access to Oracle Functions. For more
information, see Creating an Authorizer Function.
If you use the Console to include an authentication request policy (rather than by editing a
JSON file), you select the authorizer function and the application that contains it from a list.
Note that to use the Console (rather than a JSON file) to define an authentication request
policy and specify an authorizer function, your user account must belong to a group that has
been given access to the authorizer function by an IAM policy (see Create a Policy to Give API
Gateway Users Access to Functions).
where:
l "type": "TOKEN" indicates that the value being passed to the authorizer
function is an auth token.
l "token": "<token-value>" is the auth token being passed to the
authorizer function.
For example:
{
"type": "TOKEN",
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1nHyDtTwR3SEJ3z489..."
}
b. Write code in the authorizer function that returns the following JSON to API
Gateway as an HTTP 200 response when the access token has been successfully
verified:
{
"active": true,
"principal": "<user-principal>",
"scope": ["<scopes>"],
"clientId": "<client-id>",
"expiresAt": "<date-time>",
"context": {
"<key>": "<value>", ...
}
}
where:
l "active": true indicates the access token originally passed to the
authorizer function has been successfully verified.
l "principal": "<user-principal>" is the user or application obtained by
the authorizer function from the identity provider.
l "scope": ["<scopes>"] is a comma-delimited list of strings that are the
access scopes obtained by the authorizer function from the identity
provider.
l "clientId": "<client-id>" is optionally the requestor's host (for
example, the hostname or the client IP). Returning a clientId is not
required.
l "expiresAt": "<date-time>" is a date-time string in ISO-8601 format
indicating when the access token originally passed to the authorizer function
will expire. This value is used when determining how long to cache results
after calling the authorizer function.
l "context": {"<key>": "<value>", ... } is an optional comma-
delimited list of key-value pairs in JSON format to return to API Gateway.
The authorizer function can return any key-value pair for use by the API
deployment (for example, the username or email address of the caller). For
more information about using the value in the key-value pair returned by an
authorizer function as a context variable in an HTTP back end definition, see
Adding Context Variables to Policies and HTTP Back End Definitions.
For example:
{
"active": true,
"principal": "https://example.com/users/jdoe",
"scope": ["list:hello", "read:hello", "create:hello", "update:hello", "delete:hello",
"someScope"],
"clientId": "host123",
"expiresAt": "2019-05-30T10:15:30+01:00",
"context": {
"email": "[email protected]"
}
}
c. Write code that returns the following JSON to API Gateway as an HTTP 5xx
response if token verification is unsuccessful, or in the event of an error in the
authorizer function or in Oracle Functions:
{
"active": false,
"expiresAt": "<date-time>",
"context": {
"<key>": "<value>", ... "
},
"wwwAuthenticate": "<directive>"
}
where:
l "active": false indicates the access token originally passed to the
authorizer function has not been successfully verified.
l "expiresAt": "<date-time>" is a date-time string in ISO-8601 format
indicating when the access token originally passed to the authorizer function
will expire.
l "context": {"<key>": "<value>", ... } is an optional comma-
delimited list of key-value pairs in JSON format to return to API Gateway.
The authorizer function can return any key-value pair (for example, the
username or email address of the caller). Returning context key-value
pairs is not required.
l "wwwAuthenticate": "<directive>" is the value of the WWW-
Authenticate header to be returned by the authorizer function if verification
fails, indicating the type of authentication that is required (such as Basic or
Bearer). API Gateway returns the WWW-Authenticate header in the
response to the caller, along with a 401 status code. For example,
"wwwAuthenticate": "Bearer realm=\"example.com\"". For more
information, see RFC 2617 HTTP Authentication: Basic and Digest Access
Authentication.
For example:
{
"active": false,
"expiresAt": "2019-05-30T10:15:30+01:00",
"context": {
"email": "[email protected]"
},
"wwwAuthenticate": "Bearer realm=\"example.com\""
}
2. Build a Docker image from the code, push the Docker image to a Docker registry, and
create a new function in Oracle Functions based on the image. You can do this in
different ways:
l You can use the Fn Project CLI command fn deploy to build a new Docker image,
push the image to the Docker registry, and create a new function in Oracle
Functions based on the image. See Creating and Deploying Functions.
l You can use Docker commands to build the image and push it to the Docker
registry, and then use the Fn Project CLI command fn create function (or the
CreateFunction API operation) to create a new function in Oracle Functions
based on the image. See Creating Functions from Existing Docker Images.
3. Make a note of the OCID of the function you create in Oracle Functions. For example,
ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq
4. If one doesn't exist already, create an Oracle Cloud Infrastructure policy and specify a
policy statement to give API gateways access to function-related resources. The policy
enables API deployments on those API gateways to invoke the authorizer function. For
more information, see Create a Policy to Give API Gateways Access to Functions
1. Create or update an API deployment using the Console, select the From Scratch
option, and enter details on the Basic Information page.
For more information, see Deploying an API on an API Gateway by Creating an
API Deployment and Updating API Gateways and API Deployments.
2. In the API Request Policies section of the Basic Information page, click the Add
button beside Authentication and specify:
l Authentication Type: Select Custom.
l Application in <compartment-name>: The name of the application in Oracle
Functions that contains the authorizer function. You can select an application from
a different compartment.
l Function Name: The name of the authorizer function in Oracle Functions.
l Authentication Token: Whether the access token is contained in a request
header or a query parameter.
l Authentication Token Value: Depending on whether the access token is
contained in a request header or a query parameter, specify:
o Header Name: If the access token is contained in a request header, enter
the name of the header.
o Parameter Name: If the access token is contained in a query parameter,
enter the name of the query parameter.
l Enable Anonymous Access: Whether unauthenticated (that is, anonymous)
callers can access routes in the API deployment. By default, this option is not
selected. If you never want anonymous callers to be able to access routes, don't
select this option. Note that if you do select this option, you also have to explicitly
specify every route to which anonymous access is allowed by selecting
Anonymous as the Authorization Type in each route's authorization policy.
3. Click Save Changes, and then click Next to enter details for individual routes in the
API deployment on the Routes page. To specify an authorization policy that applies to
an individual route, click Show Route Request Policies, click the Add button beside
Authorization, and specify:
Note
4. Click Save Changes, and then click Next to review the details you entered for the API
deployment.
5. Click Create or Save Changes to create or update the API deployment.
6. (Optional) Confirm the API has been deployed successfully by calling it (see Calling an
API Deployed on an API Gateway).
1. Using your preferred JSON editor, edit the existing API deployment specification to
which you want to add authentication and authorization functionality, or create a new
API deployment specification (see Creating an API Deployment Specification).
At a minimum, the API deployment specification will include a routes section
containing:
2. Add an authentication request policy that applies to all routes in the API deployment
specification:
a. Insert a requestPolicies section before the routes section, if one doesn't exist
already. For example:
{
"requestPolicies": {},
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
}
}
]
}
where:
l <type-value> is the authentication type. To use an authorizer function for
authentication, specify CUSTOM_AUTHENTICATION.
l "isAnonymousAccessAllowed": <true|false> optionally indicates
whether unauthenticated (that is, anonymous) callers can access routes in
the API deployment specification. If you never want anonymous callers to
be able to access routes, set this property to false. If you don't include this
property in the authentication policy, the default of false is used. Note
that if you do include this property and set it to true, you also have to
explicitly specify every route to which anonymous access is allowed by
setting the type property to "ANONYMOUS" in each route's authorization
policy.
3. Add an authorization request policy for each route in the API deployment
specification:
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
},
"requestPolicies": {
"authorization": {
"type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS">,
"allowedScope": [ "<scope>" ]
}
}
}
]
}
where:
l "type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS"> indicates
how to grant access to the route:
o "AUTHENTICATION_ONLY": Only grant access to callers that have been
successfully authenticated. In this case, the
"isAnonymousAccessAllowed" property in the API deployment
specification's authentication policy has no effect.
o "ANY_OF": Only grant access to callers that have been successfully
authenticated, provided the authorizer function has also returned one
of the access scopes you specify in the allowedScope property. In
this case, the "isAnonymousAccessAllowed" property in the API
deployment specification's authentication policy has no effect.
o "ANONYMOUS": Grant access to all callers, even if they have not been
successfully authenticated. In this case, you must explicitly set the
"isAnonymousAccessAllowed" property to true in the API
deployment specification's authentication policy.
l "allowedScope": [ "<scope>" ] is a comma-delimited list of one or
more strings that correspond to access scopes returned by the authorizer
function. In this case, you must set the type property to "ANY_OF" (the
c. Add an authorization request policy for all remaining routes in the API
deployment specification.
Note
A JWT is a JSON-based access token sent in an HTTP request from a caller to a resource to
authenticate the caller. JWTs are issued by identity providers (for example, Oracle Identity
Cloud Service (IDCS), Auth0, Okta). When a caller attempts to access a resource and passes a
JWT to authenticate itself, the resource validates the JWT with an authorization server using a
corresponding public verification key.
A JWT comprises:
l A header, which identifies the type of token and the cryptographic algorithm used to
generate the signature.
l A payload, containing claims about the caller's identity, and the properties of the JWT
itself. A claim is a key value pair, where the key is the name of the claim. A payload is
recommended (although not required) to contain certain reserved claims with particular
names, such as expiration time (exp), audience (aud), issuer (iss), and not before
(nbf). A payload can also contain custom claims with user-defined names.
l A signature, to validate the authenticity of the JWT (derived by base64 encoding the
header and the payload).
You enable an API deployment to use JWTs for authentication and authorization by including
two different kinds of request policy in the API deployment specification:
l An authentication request policy for the entire API deployment that specifies the use of
JWTs, including how to validate them and whether unauthenticated callers can access
routes in the API deployment.
l An authorization request policy for each route that specifies the operations a caller is
allowed to perform, optionally based on values specified for the scope claim in the JWT.
Before a caller can access an API deployment that uses JWTs for authentication and
authorization, they must obtain a JWT from an identity provider.
When calling an API deployed on an API gateway, the caller provides the JWT as a query
parameter or in the header of the request. The API gateway validates the JWT using a
corresponding public verification key provided by the issuing identity provider. Using the API
deployment's authentication request policy, you can configure how the API gateway validates
JWTs:
l You can configure the API gateway to retrieve public verification keys from the identity
provider at runtime. In this case, the identity provider acts as the authorization server.
l You can configure the API gateway in advance with public verification keys already
issued by an identity provider (referred to as 'static keys'), enabling the API gateway to
verify JWTs locally at runtime without having to contact the identity provider. The result
is faster token validation.
As well as using the public verification key from the issuing identity provider to verify the
authenticity of a JWT, you can specify that reserved claims in the JWT's payload must have
particular values before the API gateway considers the JWT to be valid. By default,
API gateways validate JWTs using the expiration (exp), audience (aud), and issuer (iss)
claims, along with the not before (nbf) claim if present. You can also specify acceptable
values for custom claims. See Identity Provider Details to Use for iss and aud Claims, and for
the JWKS URI.
When the JWT has been validated, the API gateway extracts claims from the JWT's payload as
key value pairs and saves them as records in the request.auth context table for use by the
API deployment. For example, as context variables for use in an HTTP back end definition
(see Adding Context Variables to Policies and HTTP Back End Definitions). If the JWT's payload
contains the scope claim, you can use the claim's values in authorization request policies for
individual routes to specify the operations a caller is allowed to perform.
You can add authentication and authorization request policies to an API deployment
specification by:
Before you can enable authentication and authorization for API deployments using JWTs:
l An identity provider (for example, Oracle Identity Cloud Service (IDCS), Auth0) must
have already been set up to issue JWTs for users allowed to access the API deployment.
l If you want to use custom claims in authorization policies, the identity provider must be
set up to add the custom claims to the JWTs it issues.
See the identity provider documentation for more information (for example, the Oracle
Identity Cloud Service (IDCS) documentation, the Auth0 documentation).
Also note that to validate the JWT using a corresponding public verification key provided by
the issuing identity provider:
l the signing algorithm used to generate the JWT's signature must be one of RS256,
RS384, or RS512
l the public verification key must have a minimum length of 2048 bits and must not
exceed 4096 bits
1. Create or update an API deployment using the Console, select the From Scratch
option, and enter details on the Basic Information page.
For more information, see Deploying an API on an API Gateway by Creating an
API Deployment and Updating API Gateways and API Deployments.
2. In the API Request Policies section of the Basic Information page, click the Add
button beside Authentication and specify:
l Authentication Type: Select JWT.
l Authentication Token: Whether the JWT is contained in a request header or a
query parameter.
l Authentication Token Value: Depending on whether the JWT is contained in a
request header or a query parameter, specify:
XsEiCeYgglwW/KAhSSNRVdD60QlXYMWHOhXzSFDZCLf1WXxKMZCiMvVrsBIzmFEXnFmcsO2mxwlL5
/8qQudomoP+yycJ2gWPIgqsZcQRheJWxVC5ep0MeEHlvLnEvCi9utpAnjrsZCQ7plfZVPX7XORvez
wqQhBfYzwA27M2FgOOs8DOIYfqQ1Ki3DMqEppFnjLcjgQtknbTlT7YgG6tzobwig8M2KIrPjJ0Bmb
JAFH
-----END PUBLIC KEY-----
the JWT.
l Another Claim: Click to add additional claims (up to a maximum of ten).
7. Click Save Changes, and then click Next to enter details for individual routes in the
API deployment on the Routes page. To specify an authorization policy that applies to
an individual route, click Show Route Request Policies, click the Add button beside
Authorization, and specify:
l Authorization Type: How to grant access to the route. Specify:
o Any: Only grant access to callers that have been successfully authenticated,
provided the JWT has a scope claim that includes at least one of the access
scopes you specify in the Allowed Scope field. In this case, the
authentication policy's Enable Anonymous Access option has no effect.
o Anonymous: Grant access to all callers, even if they have not been
successfully authenticated using the JWT. In this case, you must have
selected the authentication policy's Enable Anonymous Access option.
o Authentication only: Only grant access to callers that have been
successfully authenticated using the JWT. In this case, the authentication
policy's Enable Anonymous Access option has no effect.
l Allowed Scope: If you selected Any as the Authorization Type, enter a
comma-delimited list of one or more strings that correspond to access scopes in
the JWT. Access will only be granted to callers that have been successfully
authenticated if the JWT has a scope claim that includes one of the access scopes
you specify. For example, read:hello
Note
8. Click Save Changes, and then click Next to review the details you entered for the API
deployment.
9. Click Create or Save Changes to create or update the API deployment.
10. (Optional) Confirm the API has been deployed successfully by calling it (see Calling an
API Deployed on an API Gateway).
1. Using your preferred JSON editor, edit the existing API deployment specification to
which you want to add authentication and authorization functionality, or create a new
API deployment specification (see Creating an API Deployment Specification).
At a minimum, the API deployment specification will include a routes section
containing:
2. Add an authentication request policy that applies to all routes in the API deployment
specification:
a. Insert a requestPolicies section before the routes section, if one doesn't exist
already. For example:
{
"requestPolicies": {},
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
}
}
]
}
where:
l <type-value> is the authentication type. To use JWTs for authentication,
specify JWT_AUTHENTICATION.
where:
n "uri": "<uri-for-jwks>" specifies the URI from which to
retrieve the JSON Web Key Set (JWKS) to use to verify the
signature on JWTs. For more information about the URI to
specify, see Identity Provider Details to Use for iss and aud
Claims, and for the JWKS URI. Note the following:
n The URI must be routable from the subnet containing the
API gateway on which the API is deployed.
n URIs that require authentication or authorization to return
the JWKS are not supported.
For example:
"publickeys": {
"type": "STATIC_KEYS",
"keys": [
{
"format": "JSON_WEB_KEY",
"kid": "master_key",
"kty": "RSA",
"n": "0vx7agoebGc...KnqDKgw",
"e": "AQAB",
"alg": "RS256",
"use": "sig"
}
]
"publickeys": {
"type": "STATIC_KEYS",
"keys": [
{
"format": "PEM",
"kid": "master_key"
"key": -----BEGIN PUBLIC KEY-----
XsEiCeYgglwW/KAhSSNRVdD60QlXYMWHOhXzSFDZCLf1WXxKMZCiMvVrsBIzmFEXnFmcsO
2mxwlL5/8qQudomoP+yycJ2gWPIgqsZcQRheJWxVC5ep0MeEHlvLnEvCi9utpAnjrsZCQ7
plfZVPX7XORvezwqQhBfYzwA27M2FgOOs8DOIYfqQ1Ki3DMqEppFnjLcjgQtknbTlT7YgG
6tzobwig8M2KIrPjJ0BmbJAFH-----END PUBLIC KEY-----
}
]
{
"requestPolicies": {
"authentication": {
"type": "JWT_AUTHENTICATION",
"isAnonymousAccessAllowed": false,
"issuers": ["https://identity.oraclecloud.com/"],
"tokenHeader": "Authorization",
"tokenAuthScheme": "Bearer",
"audiences": ["api.dev.io"],
"publickeys": {
"type": "STATIC_KEYS",
"keys": [
{
"format": "JSON_WEB_KEY",
"kid": "master_key",
"kty": "RSA",
"n": "0vx7agoebGc...KnqDKgw",
"e": "AQAB",
"alg": "RS256",
"use": "sig"
}
]
},
"verifyClaims": [
{
"key": "is_admin",
"values": ["service:app", "read:hello"],
"isRequired": true
}
],
"maxClockSkewInSeconds": 10
}
},
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
}
}
]
}
3. Add an authorization request policy for each route in the API deployment
specification:
a. Insert a requestPolicies section after the first route's backend section, if one
doesn't exist already. For example:
{
"requestPolicies": {
"authentication": {
"type": "JWT_AUTHENTICATION",
"isAnonymousAccessAllowed": false,
"issuers": ["https://identity.oraclecloud.com/"],
"tokenHeader": "Authorization",
"tokenAuthScheme": "Bearer",
"audiences": ["api.dev.io"],
"publickeys": {
"type": "STATIC_KEYS",
"keys": [
{
"format": "JSON_WEB_KEY",
"kid": "master_key",
"kty": "RSA",
"n": "0vx7agoebGc...KnqDKgw",
"e": "AQAB",
"alg": "RS256",
"use": "sig"
}
]
},
"verifyClaims": [
{
"key": "is_admin",
"values": ["service:app", "read:hello"],
"isRequired": true
}
],
"maxClockSkewInSeconds": 10
}
},
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
},
"requestPolicies": {}
}
]
}
},
"verifyClaims": [
{
"key": "is_admin",
"values": ["service:app", "read:hello"],
"isRequired": true
}
],
"maxClockSkewInSeconds": 10
}
},
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
},
"requestPolicies": {
"authorization": {
"type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS">,
"allowedScope": [ "<scope>" ]
}
}
}
]
}
where:
l "type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS"> indicates
how to grant access to the route:
o "AUTHENTICATION_ONLY": Only grant access to callers that have been
successfully authenticated. In this case, the
"isAnonymousAccessAllowed" property in the API deployment
specification's authentication policy has no effect.
"kty": "RSA",
"n": "0vx7agoebGc...KnqDKgw",
"e": "AQAB",
"alg": "RS256",
"use": "sig"
}
]
},
"verifyClaims": [
{
"key": "is_admin",
"values": ["service:app", "read:hello"],
"isRequired": true
}
],
"maxClockSkewInSeconds": 10
}
},
"routes": [
{
"path": "/hello",
"methods": ["GET"],
"backend": {
"type": "ORACLE_FUNCTIONS_BACKEND",
"functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
},
"requestPolicies": {
"authorization": {
"type": "ANY_OF",
"allowedScope": [ "read:hello" ]
}
}
}
]
}
c. Add an authorization request policy for all remaining routes in the API
deployment specification.
Note
Identity Provider Details to Use for iss and aud Claims, and for the JWKS URI
The identity provider that issued the JWT determines the allowed values you have to specify
for the issuer (iss) and the audience (aud) claims in the JWT. Which identity provider issued
the JWT also determines the URI from which to retrieve the JSON Web Key Set (JWKS) to
verify the signature on the JWT. Note that URIs that require authentication or authorization to
return the JWKS are not supported.
Use the following table to find out what to specify for JWTs issued by the Oracle Identity Cloud
Service (IDCS), Okta, and Auth0 identity providers.
To verify the signature on a JWT, API gateways require the following key parameters are
present in either the JWKS returned from a URI or the static JSON Web Key you specify.
Key Notes
Parameter
kid The identifier of the key used to sign the JWT. The value must match the kid
claim in the JWT header. For example, master_key.
kty The type of the key used to sign the JWT. Note that RSA is currently the only
supported key type.
use or key_ If the use parameter is present, then it must be set to sig. If the key-ops
ops parameter is present, then verify must be one of the valid values.
alg The signing algorithm (if present) must be set to one of RS256, RS384 or
RS512.
If you have waited more than a few minutes for the API gateway to be shown with an Active
state (or if the API gateway creation operation has failed):
1. Click the name of the API gateway, and click Work Requests to see an overview of the
API gateway creation operation.
2. Click the Create Gateway operation to see more information about the operation
(including error messages, log messages, and the status of associated resources) that
will help to diagnose the cause of the problem.
If you have waited more than a few minutes for the API deployment to be shown with an
Active state (or if the API deployment creation operation has failed):
1. Click the name of the API deployment, and click Work Requests to see an overview of
the API deployment creation operation.
2. Click the Create Deployment operation to see more information about the operation
(including error messages, log messages, and the status of associated resources) that
will help to diagnose the cause of the problem .
This message indicates that there are not enough private IP addresses available to create the
API gateway in the specified subnet. An API gateway consumes three private IP addresses in
the subnet.
To address this issue, use a subnet that has at least three available private IP addresses.
This message indicates that there are not enough private IP addresses available to create the
API gateway in the specified subnet. An API gateway consumes three private IP addresses in
the subnet.
To address this issue, use a subnet that has at least three available private IP addresses.
This message indicates that there are not enough public IP addresses available to create the
public API gateway in the specified subnet's compartment. When creating a new public API
gateway, an attempt is made to create a new public IP address in the subnet's compartment.
The attempt to create the new public IP address fails if the quota for public IP addresses is
exceeded in that compartment or tenancy. Note the public IP address is in addition to the
three private IP addresses consumed by all API gateways.
This message indicates that you cancelled the work request to create the API gateway. The
API gateway is shown with a status of Failed.
This message indicates that the API Gateway service cannot access the subnet specified for
the new API gateway.
This topic describes the metrics emitted by the API Gateway service in the oci_apigateway
metric namespace.
Resources: gateways
To view a default set of metrics charts in the Console, navigate to the API gateway you're
interested in, and then click Metrics. You also can use the Monitoring service to create
custom queries.
Prerequisites
IAM policies: To monitor resources, 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. The policy must give you access to the monitoring services as well as the
resources being monitored. 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 more information on
user authorizations for monitoring, see the Authentication and Authorization section for the
related service: Monitoring or Notifications.
RESOURCEID
DEPLOYMENTID
ROUTE
HTTPM ETHODTYPE
The HTTP methods of incoming connections accepted by the back-end service (such as
GET, HEAD, POST, PUT, DELETE).
HTTPSTATUS C ODE
The HTTP response status code received from the API gateway (such as 200, 201, 502,
504).
HTTPSTATUS C ATEGORY
The category of the HTTP response status code received from the API gateway (such as
2xx, 3xx, 4xx, 5xx).
BACKENDTYPE
The type of back end by which an API gateway routes requests to a back-end service
(such as HTTP_BACKEND, ORACLE_FUNCTIONS_BACKEND, STOCK_RESPONSE_
BACKEND).
BACKENDHTTPSTATUS C ODE
The HTTP response status code received from the back end (such as 200, 201, 502, 504).
BACKENDHTTPSTATUS C ATEGORY
The category of the HTTP response status code received from the back end (such as 2xx,
3xx, 4xx, 5xx).
httpStatusCategory
backendType
httpStatusCategory
backendType
httpStatusCategory
backendType
httpStatusCategory
backendType
backendHttpStatusCode
backendHttpStatusCatego
ry
httpStatusCategory
To view default metric charts for all the API gateways in a compartment
1. Open the navigation menu. Under Solutions and Platform, go to Monitoring and
click Service Metrics.
2. Select the region you are using with API Gateway
3. Select the compartment containing the API gateways for which you want to view
metrics.
4. For Metric Namespace, select oci_apigateway.
The Service Metrics page dynamically updates the page to show charts for each
metric that is emitted by the selected metric namespace. For more information about
the emitted metrics, see Available Metrics: oci_apigateway.
For more information about monitoring metrics and using alarms, see Monitoring Overview.
For information about notifications for alarms, see Notifications Overview.
l Use Archive Storage for data to which you seldom or rarely access, but that must be
retained and preserved for long periods of time. The cost efficiency of the Archive
Storage offsets the long lead time required to access the data.
l Use Object Storage for data to which you need fast, immediate, and frequent access.
Data accessibility and performance justifies a higher price to store data in the Object
Storage. For more information, see Overview of Object Storage.
Archive Storage is Always Free eligible. For more information about Always Free resources,
including additional capabilities and limitations, see Oracle Cloud Infrastructure Free Tier.
Important
Use the following Object Storage resources to store and manage Archive Storage data.
Buckets
Buckets are logical containers for storing objects. A bucket is associated with a single
compartment that has policies that determine what actions a user can perform on a bucket
and on all the objects in the bucket.
You decide which storage tier (Archive Storage or standard Object Storage) is appropriate for
your data when you initially create the bucket container for your data. The storage tier is
expressed as a property of the bucket. A bucket's storage tier property sets the initial storage
tier of objects added to the bucket. However, if objects meet the criteria of an object lifecycle
policy rule, Object Storage can automatically archive objects, while remaining in the standard
tier bucket.
Once set, you cannot change the storage tier property for a bucket:
In addition to the inability to change the storage tier designation of a bucket, there are other
reasons why storage tier selection for buckets requires careful consideration:
l The minimum retention requirement for Archive Storage is 90 days. If you delete
objects from Archive Storage before the minimum retention requirements are met, you
are charged a deletion penalty. The deletion penalty is the prorated cost of storing the
You can use object lifecycle policy rules to automatically delete objects in an Archive Storage
bucket based on the age of the object.
Important
See Managing Buckets for detailed instructions on creating an Archive Storage bucket.
Objects
Any type of data, regardless of content type, is stored as an object. The object is composed of
the object itself and metadata about the object. Each object is stored in a bucket.
You upload objects to an Archive Storage bucket the same way you upload objects to a
standard Object Storage bucket. The difference is that when you upload an object to an
Archive Storage bucket, the object is immediately archived. You must first restore the object
before you can download it.
Archived objects are displayed in the object listing of a bucket. You can also display the
details of each object.
See Managing Objects for detailed instructions on uploading objects to an Archive Storage
bucket.
To download an object from Archive Storage, you must first restore the object. Restoration
takes at most an hour from the time an Archive Storage restore request is made, to the time
the first byte of data is retrieved. The retrieval time metric is measured as Time To First Byte
(TTFB). How long the full restoration takes, depends on the size of the object. You can
determine the status of the restoration by looking at the object Details. Once the status
shows as Restored, you can then download the object.
After an object is restored, you have a window of time to download the object. By default, you
have 24 hours to download an object, but you can alternatively specify a time from 1 to 240
hours. You can find out how much of the download time is remaining by looking at Available
for Download in object Details. After the allotted download time expires, the object returns
to Archive Storage. You can always access the metadata for an object, regardless of whether
the object is in an archived or restored state.
See Managing Objects for detailed instructions on restoring, checking status of, and
downloading Archive Storage objects.
The syntax for CLI commands includes specifying a service. You use the Object Storage
service designation oci os to manage Archive Storage using the CLI.
l The REST API provides the most functionality, but requires programming expertise. API
Reference and Endpoints provides endpoint details and links to the available API
reference documents. For general information about using the API, see REST APIs.
Object Storage is accessible with the following APIs:
o Object Storage Service
o Amazon S3 Compatibility API
o Swift API (for use with Oracle RMAN)
l Oracle Cloud Infrastructure provides SDKs that interact with Archive Storage and Object
Storage without you having to create a framework. For general information about using
the SDKs, see Software Development Kits and Command Line Interface.
An administrator in your organization needs to set up groups, compartments, and policies that
control which users can access which services, which resources, and the type of access. For
example, the policies control things like who can create users, create and manage the cloud
network, launch instances, create buckets, and download objects. For more information, see
Getting Started with Policies. For specific details about writing policies for each of the
different services, see the Policy Reference. For specific details about writing policies for
Archive Storage, see Details for Object Storage, Archive Storage, and Data Transfer.
If you’re a regular user (not an administrator) who needs to use the Oracle Cloud
Infrastructure resources that your company owns, contact your administrator to set up a user
ID for you. The administrator can confirm which compartment or compartments you should be
using.
For administrators:
l The policy Let Object Storage admins manage buckets and objects lets the specified
group do everything with buckets and objects.
l Users that need to restore archived objects require the OBJECT_RESTORE permission.
WORM Compliance
Use retention rules to achieve WORM compliance with Archive Storage so that data once
written, cannot be overwritten. Retention rules are configured at the bucket level and are
applied to all individual objects in the bucket. You cannot update, overwrite, or delete objects
or object metadata until the retention rule is deleted (indefinite rule) or for the duration
specified (time-bound rules).
Overview of Audit
The Oracle Cloud Infrastructure Audit service automatically records calls to all supported
Oracle Cloud Infrastructure public application programming interface (API) endpoints as log
events. Currently, all services support logging by Audit. Object Storage service supports
logging for bucket-related events, but not for object-related events. Log events recorded by
the Audit service include API calls made by the Oracle Cloud Infrastructure Console,
Command Line Interface (CLI), Software Development Kits (SDK), your own custom clients,
or other Oracle Cloud Infrastructure services. Information in the logs includes the following:
Each log event includes a header ID, target resources, timestamp of the recorded event,
request parameters, and response parameters. You can view events logged by the Audit
service by using the Console, API, or the SDK for Java. Data from events can be used to
perform diagnostics, track resource usage, monitor compliance, and collect security-related
events.
The new schema is being implemented over time. Oracle continues to provide Audit logs in the
version 1 format, but you cannot access version 1 format logs from the Console. The Console
displays only the version 2 format logs. However, not all resources are emitting logs using the
version 2 schema. For those services that are not emitting in the version 2 format, Oracle
converts version 1 logs to version 2 logs, leaving fields blank if information for the version 2
schema cannot be determined.
For general information about using the API, see REST APIs.
An administrator in your organization needs to set up groups, compartments, and policies that
control which users can access which services, which resources, and the type of access. For
example, the policies control who can create new users, create and manage the cloud
network, launch instances, create buckets, download objects, etc. For more information, see
Getting Started with Policies. For specific details about writing policies for each of the
different services, see Policy Reference.
If you’re a regular user (not an administrator) who needs to use the Oracle Cloud
Infrastructure resources that your company owns, contact your administrator to set up a user
ID for you. The administrator can confirm which compartment or compartments you should be
using.
Administrators: For an example of policy that gives groups access to audit logs, see Required
IAM Policy. To modify the Audit log retention period, you must be a member of the
Administrators group. See The Administrators Group and Policy.
Resource Identifiers
Most types of Oracle Cloud Infrastructure resources have a unique, Oracle-assigned identifier
called an Oracle Cloud ID (OCID). For information about the OCID format and other ways to
identify your resources, see Resource Identifiers.
Event Envelope
These attributes for an event envelope are the same for all events. The structure of the
envelope follows the CloudEvents industry standard format hosted by the Cloud Native
Computing Foundation ( CNCF).
Property Description
Note
eventID The UUID of the event. This identifier is not an OCID, but
just a unique ID for the event.
Property Description
Note
eventTypeVersion The version of the event type. This version applies to the
payload of the event, not the envelope. Use
cloudEventsVersion to determine the version of the
envelope.
Payload
The data in these fields depends on which service produced the event log and the event type it
defines.
Data
Property Description
data.eventGroupingId This value links multiple audit events that are part of the
same API operation. For example, a long running
API operation that emits an event at the start and the end
of the operation.
Example: LaunchInstance
Identity
The identity object contains the following attributes.
Property Description
data.identity.userAgent The user agent of the client that made the request.
Request
The request object contains the following attributes.
Property Description
Example: GET
Example:
/20160918/instances/ocid1.instance.oc1.phx.
<unique_ID>
Response
The response object contains the following attributes.
Property Description
Property Description
State Change
The state change object contains the following attributes.
Property Description
"eventId": "<unique_ID>",
"eventTime": "2019-09-18T00:10:59.252Z",
"contentType": "application/json",
"data": {
"eventGroupingId": null,
"eventName": "GetInstance",
"compartmentId": "ocid1.tenancy.oc1..<unique_ID>",
"compartmentName": "compartmentA",
"resourceName": "my_instance",
"resourceId": "ocid1.instance.oc1.phx.<unique_ID>",
"availabilityDomain": "<availability_domain>",
"freeformTags": null,
"definedTags": null,
"identity": {
"principalName": "ExampleName",
"principalId": "ocid1.user.oc1..<unique_ID>",
"authType": "natv",
"callerName": null,
"callerId": null,
"tenantId": "ocid1.tenancy.oc1..<unique_ID>",
"ipAddress": "172.24.80.88",
"credentials": null,
"userAgent": "Jersey/2.23 (HttpUrlConnection 1.8.0_212)",
"consoleSessionId": null
},
"request": {
"id": "<unique_ID>",
"path": "/20160918/instances/ocid1.instance.oc1.phx.<unique_ID>",
"action": "GET",
"parameters": {},
"headers": {
"opc-principal": [
"{\"tenantId\":\"ocid1.tenancy.oc1..<unique_ID>\",\"subjectId\":\"ocid1.user.oc1..
ID>\",\"claims\":[{\"key\":\"pstype\",\"value\":\"natv\",\"issuer\":\"authService.oracle.com\"},
{\"key\":\"h_host\",\"value\":\"iaas.r2.oracleiaas.com\",\"issuer\":\"h\"},{\"key\":\"h_opc-request-
id\",\"value\":\"<unique_ID>\",\"issuer\":\"h\"},
{\"key\":\"ptype\",\"value\":\"user\",\"issuer\":\"authService.oracle.com\"},{\"key\":\"h_
date\",\"value\":\"Wed, 18 Sep 2019 00:10:58 UTC\",\"issuer\":\"h\"},{\"key\":\"h_
accept\",\"value\":\"application/json\",\"issuer\":\"h\"},
{\"key\":\"authorization\",\"value\":\"Signature headers=\\\"date (request-target) host accept opc-
request-id\\\",keyId=\\\"ocid1.tenancy.oc1..<unique_ID>/ocid1.user.oc1..<unique_
ID>/8c:b4:5f:18:e7:ec:db:08:b8:fa:d2:2a:7d:11:76:ac\\\",algorithm=\\\"rsa-pss-
sha256\\\",signature=\\\"<unique_ID>\\\",version=\\\"1\\\"\",\"issuer\":\"h\"},{\"key\":\"h_(request-
target)\",\"value\":\"get /20160918/instances/ocid1.instance.oc1.phx.<unique_ID>\",\"issuer\":\"h\"}]}"
],
"Accept": [
"application/json"
],
"X-Oracle-Auth-Client-CN": [
"splat-proxy-se-02302.node.ad2.r2"
],
"X-Forwarded-Host": [
"compute-api.svc.ad1.r2"
],
"Connection": [
"close"
],
"User-Agent": [
"Jersey/2.23 (HttpUrlConnection 1.8.0_212)"
],
"X-Forwarded-For": [
"172.24.80.88"
],
"X-Real-IP": [
"172.24.80.88"
],
"oci-original-url": [
"https://iaas.r2.oracleiaas.com/20160918/instances/ocid1.instance.oc1.phx.<unique_
],
"opc-request-id": [
"<unique_ID>"
],
"Date": [
"Wed, 18 Sep 2019 00:10:58 UTC"
]
}
},
"response": {
"status": "200",
"responseTime": "2019-09-18T00:10:59.278Z",
"headers": {
"ETag": [
"<unique_ID>"
],
"Connection": [
"close"
],
"Content-Length": [
"1828"
],
"opc-request-id": [
"<unique_ID>"
],
"Date": [
"Wed, 18 Sep 2019 00:10:59 GMT"
],
"Content-Type": [
"application/json"
]
},
"payload": {
"resourceName": "my_instance",
"id": "ocid1.instance.oc1.phx.<unique_ID>"
},
"message": null
},
"stateChange": {
"previous": null,
"current": null
},
"additionalDetails": {
"imageId": "ocid1.image.oc1.phx.<unique_ID>",
"shape": "VM.Standard1.1",
"type": "CustomerVmi"
}
}
}
When viewing events logged by Audit, you might be interested in specific activities that
happened in the tenancy or compartment and who was responsible for the activity. You will
need to know that the approximate time and date something happened and the compartment
in which it happened to display a list of log events that includes the activity in question. List
log events by specifying a time range on the 24-hour clock in Greenwich Mean Time (GMT),
calculating the offset for your local time zone, as appropriate. New activity is appended to the
existing list, usually within 15 minutes of the API call, though processing time can vary.
For administrators: The following policy statement gives the specified group (Auditors) the
ability to view all the Audit event logs in the tenancy:
Allow group Auditors to read audit-events in tenancy
To give the group access to the Audit event logs in a specific compartment only (ProjectA),
write a policy like the following:
Allow group Auditors to read audit-events in compartment ProjectA
If you're new to policies, see Getting Started with Policies and Common Policies. For more
details about policies for the Audit, see Details for the Audit Service.
For example, users begin to report that their attempts to log in are failing. You want to use
Audit to research the problem. Adjust the date and time to search for corresponding failures
during a window of time that starts a little before the events were reported. Look for
corresponding failures and similar operations preceding the failures to correlate a reason for
the failures.
Note
You can filter results by request actions to zero in on only the events with operations that
interest you. For example, say that you only want to know about instances that were deleted
during a specific time frame. Select a delete request action filter to see only the events with
delete operations.
You can also filter by keywords. Keyword filters are powerful when combined with the values
from audit event fields. For example, say that you know the user name of an account and
want a list of all activity by that account in a particulate time frame. Do a search using the
user name as a keyword filter.
Every audit event contains the same fields, so search for values from those fields. To get a
better understanding of what values are available, see Contents of an Audit Log Event.
Note
6. (Optional) In Request Action Types, specify one or more operations with which to
filter results.
l GET
l POST
l PUT
l PATCH
l DELETE
7. (Optional) In the Keywords box, type the text you want to find and click Search.
Tip: If you want to find log events with a specific status code, include quotes (") around
the code to avoid results that have those numbers embedded in a longer string.
The results are updated to include only log events that were processed within the time range
and filters you specified. If an event occurred in the recent past, you might have to wait to see
it in the list. The service typically requires up to 15 minutes for processing.
If there are more than 100 results for the specified time range, you can click the right arrow
next to the page number at the bottom of the page to advance to the next page of log events.
Tip
If you want to view all the key-value pairs in a log event, see To view the details of a log
event.
l To see only the top-level details, click the down arrow to the right of an event.
l To see lower-level details, click { . . . } to the right of the collapsed parameter.
l To copy an entire event, click the clipboard icon to the right of the event parameter.
l To copy a portion of an event, click the clipboard icon to the right of the nested
parameter or value you want to copy.
The log event is copied to your clipboard. The Audit service logs events in JSON format. You
can paste the log event details into a text editor to save and review later or to use with
standard log analysis tools.
l ListEvents
Note
Retention period is a tenancy-level setting. The value of the retention period setting affects all
regions and all compartments. You can't set different retention periods for different regions or
compartments.
The tenancy details are displayed. The Audit Retention Period is displayed under
Tenancy Information.
2. Click Edit Audit Retention Policy. Enter the number of days you want to retain the
audit logs for. The minimum you can set the value to is 90 and the maximum is 365.
This value is enforced for all regions and all compartments in the tenancy.
3. Click Submit.
Note
Use the following operations to manage the log retention period configuration:
l GetConfiguration
l UpdateConfiguration
Highlights
l Administrators have full control of the buckets and can provide access to others with
IAM policy statements.
l Exported logs remain available indefinitely.
Tip
l Specify all the regions you want exported in your request. If you only request some
regions, then decide later you want to add other regions, you must make another
request.
l To disable your bulk export, contact Oracle support. New logs will stop being added to
the bucket, and audit logs will only be available through the Console, based on the
retention period you have defined.
For example:
Note
Oracle support creates buckets for audit log exports using the following naming format:
oci-logs._audit.<compartment_OCID>
For example:
oci-logs._audit.ocid1compartment.oc1..<unique_ID>
Important
<region>/<ad>/<YYYY-MM-DDTHH:MMZ>[_<seqNum>].log.gz
l <region> identifies the region where the audit events were generated.
l <ad> identifies the availability domain where the audit events were generated.
l <YYYY-MM-DDTHH:MMZ> identifies the start time of the earliest audit event listed in
the object.
l [_<seqNum>] identifies a conditional sequence number. If present, this number means
that either an event came in late or the object became too large to write. Sequence
numbers start at two. Apply multiple sequence numbers to the original object in the
order listed.
For example:
us-phoenix-1/ad1/2019-03-21T00:00Z.log.gz
us-phoenix-1/ad1/2019-03-21T00:00Z_2.log.gz
File Format
Files list a single audit event per line. For more information, see Contents of an Audit Log
Event.
Note
l Instance: A bare metal or virtual machine (VM) host running in the cloud.
l Volume attachment: There are two types of volume attachments:
o iSCSI: A TCP/IP-based standard used for communication between a volume and
attached instance.
o Paravirtualized: A virtualized attachment available for VMs.
l Volume: There are two types of volumes:
o Block volume: A detachable block storage device that allows you to dynamically
expand the storage capacity of an instance.
o Boot volume: A detachable boot volume device that contains the image used to
boot a Compute instance. See Boot Volumes for more information.
Block Volume is Always Free eligible. For more information about Always Free resources,
including additional capabilities and limitations, see Oracle Cloud Infrastructure Free Tier.
A common usage of Block Volume is adding storage capacity to an Oracle Cloud Infrastructure
instance. After you have launched an instance and set up your cloud network, you can create a
block storage volume through the Console or API. Then, you attach the volume to an instance
using a volume attachment. After the volume is attached, you connect to the volume from
your instance's guest OS using iSCSI. The volume can then be mounted and used by your
instance.
A Block Volume volume can be detached from an instance and moved to a different instance
without the loss of data. This data persistence enables you to migrate data between instances
and ensures that your data is safely stored, even when it is not connected to an instance. Any
data remains intact until you reformat or delete the volume.
To move your volume to another instance, unmount the drive from the initial instance,
terminate the iSCSI connection, and attach the volume to the second instance. From there,
you connect and mount the drive from that instance's guest OS to have access to all of your
data.
Additionally, Block Volume volumes offer a high level of data durability compared to standard,
attached drives. All volumes are automatically replicated for you, helping to protect against
data loss, see Block Volume Durability.
When you terminate an instance, you can keep the associated boot volume and use it to
launch a new instance with a different instance type or shape. This allows you to easily switch
from a bare metal instance to a VM instance and vice versa, or scale up or scale down the
number of cores for an instance. See Creating an Instance for steps to launch an instance
based on a boot volume.
Important
iSCSI
iSCSI attachments are the only option when connecting a block volume to any of the following
types of instances:
After the volume is attached, you need to log in to the instance and use the iscsiadm
command-line tool to configure the iSCSI connection. For more information about the
additional configuration steps required for iSCSI attachments, see iSCSI Commands and
Information, Connecting to a Volume, and Disconnecting From a Volume.
Paravirtualized
Paravirtualized attachments are an option when attaching volumes to the following types of
VM instances:
l For VM instances launched from Oracle-provided images, you can select this option for
Linux-based images published in December 2017 or later, and Windows images
published in February 2018 or later.
l For VM instances launched from custom images, the volume attachment type is based
on the volume attachment type from the VM the custom image was created from.
After you attach a volume using the paravirtualized attachment type, it is ready to use, and
you do not need to run any additional commands. However, because of the overhead of
virtualization, this reduces the maximum IOPS performance for larger block volumes.
l Read/write: This is the default option for volume attachments. With this option, an
instance can read and write data to the volume.
l Read/write, shareable: With this option, you can attach a volume to more than one
instance at a time and those instances can read and write data to the volume. To
prevent data corruption from uncontrolled read/write operations with multiple instance
volume attachments you must install and configure a cluster-aware solution for system
before you can use the volume, see Configuring Multiple Instance Volume Attachments
with Read/Write Access for more information.
l Read-only: With this option, an instance can only read data on the volume. It cannot
update data on the volume. Specify this option to safeguard data against accidental or
malicious modifications.
To change the access type for a block volume, you need to detach the volume and specify the
new access type when you reattach the volume. For more information, see Detaching a
Volume and Attaching a Volume.
The access type for boot volumes is always read/write. If you want to change the access type,
you need to stop the instance and detach the boot volume. You can then reattach it to another
instance as a block volume, with read-only specified as the access type. For more
information, see Detaching a Boot Volume and Attaching a Volume.
Device Paths
When you attach a block volume to a compatible Linux-based instance, you can select a
device path that remains consistent between instance reboots. This enables you to refer to the
volume using a consistent device path. For example, you can use the device path when you
set options in the /etc/fstab file to automatically mount the volume on instance boot.
Consistent device paths are supported on instances when all of the following things are true:
For instances launched using the image OCID or an existing boot volume, if the source image
supports consistent device paths, the instance supports device paths.
Consistent device paths are not supported on Linux-based partner images or custom images
that are created from other sources. This feature does not apply to Windows-based images.
Important
For more information about consistent device paths, see Connecting to Volumes With
Consistent Device Paths.
Resource Identifiers
Most types of Oracle Cloud Infrastructure resources have a unique, Oracle-assigned identifier
called an Oracle Cloud ID (OCID). For information about the OCID format and other ways to
identify your resources, see Resource Identifiers.
guide. For a list of available SDKs, see Software Development Kits and Command Line
Interface.
For general information about using the API, see REST APIs.
An administrator in your organization needs to set up groups, compartments, and policies that
control which users can access which services, which resources, and the type of access. For
example, the policies control who can create new users, create and manage the cloud
network, launch instances, create buckets, download objects, etc. For more information, see
Getting Started with Policies. For specific details about writing policies for each of the
different services, see Policy Reference.
If you’re a regular user (not an administrator) who needs to use the Oracle Cloud
Infrastructure resources that your company owns, contact your administrator to set up a user
ID for you. The administrator can confirm which compartment or compartments you should be
using.
Monitoring Resources
You can monitor the health, capacity, and performance of your Oracle Cloud Infrastructure
resources by using metrics, alarms, and notifications. For more information, see Monitoring
Overview and Notifications Overview.
Moving Resources
You can move Block Volume resources such as block volumes, boot volumes, volume
backups, volume groups, and volume group backups from one compartment to another. For
more information, see Move Block Volume Resources Between Compartments.
Tagging Resources
You can apply tags to your resources to help you organize them according to your business
needs. You can apply tags at the time you create a resource, or you can update the resource
later with the desired tags. For general information about applying tags, see Resource Tags.
Note
You have the option to encrypt all of your volumes and their backups using the keys that you
own and manage using the Vault service, for more information see Overview of Vault. If you
do not configure a volume to use the Vault service or you later unassign a key from the
volume, the Block Volume service uses the Oracle-provided encryption key instead. This
applies to both encryption at-rest and in-transit encryption.
For how to use your own key for new volumes, see Creating a Volume. See To assign a key to
an existing Block Volume for how to assign or change the key for an existing volume.
All the data moving between the instance and the block volume is transferred over an internal
and highly secure network. If you have specific compliance requirements related to the
encryption of the data while it is moving between the instance and the block volume, the Block
Volume service provides the option to enable in-transit encryption for paravirtualized volume
attachments on virtual machine (VM) instances.
Important
The Block Volume service's elastic performance feature enables you to dynamically change
the volume performance. You can select one of the following volume performance options for
your block volumes:
l Balanced
l Higher Performance
l Lower Cost
For more information about this feature and the performance options, see Block Volume
Elastic Performance and Changing the Performance of a Volume
See Service Limits for a list of applicable limits and instructions for requesting a limit
increase. To set compartment-specific limits on a resource or resource family, administrators
can use compartment quotas.
Once the volume is attached, you need to log on to the instance and use the iscsiadm
command-line tool to configure the iSCSI connection. After you configure the volume, you can
mount it and use it like a normal hard drive.
To enhance security, Oracle enforces an iSCSI security protocol called CHAP that provides
authentication between the instance and volume.
l IP address
l Port
l CHAP user name and password (if enabled)
l IQN
Note
The Console provides this information on the details page of the volume's attached instance.
Click the Actions icon (three dots) on your volume's row, and then click iSCSI Information.
The system also returns this information when the AttachVolume API operation completes
successfully. You can re-run the operation with the same parameter values to review the
information.
If you are using custom images, you should update the iscsid service configuration by
modifying the /etc/iscsi/iscsid.conf file.
Additional Reading
There is a wealth of information on the internet about iSCSI and CHAP. If you need more
information on these topics, try the following pages:
Volume Groups
The Oracle Cloud Infrastructure Block Volume service provides you with the capability to
group together multiple volumes in a volume group. A volume group can include both types of
volumes, boot volumes, which are the system disks for your Compute instances, and block
volumes for your data storage. You can use volume groups to create volume group backups
and clones that are point-in-time and crash-consistent.
Similarly, you can also clone an entire volume group in a time-consistent and crash-consistent
manner. A deep disk-to-disk and fully isolated clone of a volume group, with all the volumes
associated in it, becomes available for use within a matter of seconds. This speeds up the
process of creating new environments for development, quality assurance, user acceptance
testing, and troubleshooting.
For more information about Block Volume-backed system disks, see Boot Volumes. For more
information about Block Volume backups see Overview of Block Volume Backups. See Cloning
a Volume for more information about Block Volume clones.
This capability is available using the Console, command line interface (CLI), SDKs, or REST
APIs.
Volume groups and volume group backups are high-level constructs that allow you to group
together multiple volumes. When working with volume groups and volume group backups,
keep the following in mind:
l You can only add a volume to a volume group when the volume status is available.
l You can add up to 32 volumes in a volume group, up to a maximum size limit of 128 TB.
For example, if you wanted to add 32 volumes of equal size to a volume group, the
maximum size for each volume would be 4 TB. Or you could add volumes that vary in
size, however the overall combined size of all the block and boot volumes in the volume
group must be 128 TB or less. Make sure you account for the size of any boot volumes in
your volume group when considering volume group size limits.
l Each volume may only be in one volume group.
l When you clone a volume group, a new group with new volumes are created. For
example, if you clone a volume group containing three volumes, once this operation is
complete, you will now have two separate volume groups and six different volumes with
nothing shared between the volume groups.
l When you update a volume group using the CLI, SDKs, or REST APIs you need to specify
all the volumes to include in the volume group each time you use the update operation.
If you do not include a volume ID in the update call, that volume will be removed from
the volume group.
l When you delete a volume group the individual volumes in the group are not deleted,
only the volume group is deleted.
l When you delete a volume that is part of a volume group you must first remove it from
the volume group before you can delete it.
l When you delete a volume group backup, all the volume backups in the volume group
backup are deleted.
Warning
For administrators: The policy in Let volume admins manage block volumes, backups, and
volume groups lets the specified group do everything with block volumes, backups, and
volume groups.
See the following policy examples for working with volume groups:
l Let users create a volume group lets the specified group create a volume group from a
set of volumes.
l Let users clone a volume group lets the specified group clone a volume group from an
existing volume group.
l Let users create a volume group backup lets the specified group create a volume group
backup.
l Let users restore a volume group backup lets the specified group create a volume group
by restoring a volume group backup.
Tip
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
Tagging Resources
You can apply tags to your resources to help you organize them according to your business
needs. You can update the resource later with the desired tags. For general information about
applying tags, see Resource Tags.
l Volumes: For each volume you want to add, select the compartment containing
the volume and then the volume to add. Click + Volume to add additional
volumes.
4. Click Create Volume Group.
Note
Note
For example:
oci bv volume-group list --compartment-id ocid1.compartment.oc1..<unique_ID>
For example:
oci bv volume-group create --compartment-id ocid1.compartment.oc1..<unique_ID> --availability-domain
ABbv:PHX-AD-1 --source-details '{"type": "volumeIds", "volumeIds":["ocid1.volume.oc1.phx.<unique_ID_1>",
"ocid1.volume.oc1.phx.<unique_ID_2>"]}'
For example:
For example:
oci bv volume-group create --compartment-id ocid1.compartment.oc1..<unique_ID> --availability-domain
ABbv:PHX-AD-1 --source-details '{"type": "volumeGroupBackupId", "volumeGroupBackupId":
"ocid1.volumegroup.oc1.sea.<unique_ID>"}'
For example:
oci bv volume-group get --volume-group-id ocid1.volumegroup.oc1.phx.<unique_ID>
You can update the volume group display name along with adding or removing volumes from
the volume group. The volume group is updated to include only the volumes specified in the
update operation. This means that you need to specify the volume IDs for all of the volumes in
the volume group each time you update the volume group.
The following example changes the volume group's display name for a volume group with two
volumes:
oci bv volume-group update --volume-group-id ocid1.volumegroup.oc1.phx.<unique_ID> --volume-ids '
["ocid1.volume.oc1.phx.<unique_ID_1>","ocid1.volume.oc1.phx.<unique_ID_2>"]' --display-name "new display
name"
If you specify volumes in the command that are not part of the volume group they are added
to the group. Any volumes not specified in the command are removed from the volume group.
When you delete a volume group, the individual volumes in the group are not deleted, only the
volume group is deleted.
For example:
oci bv volume-group delete --volume-group-id ocid1.volumegroup.oc1.phx.<unique_ID>
For example:
oci bv volume-group-backup list --compartment-id ocid1.compartment.oc1..<unique_ID>
For example:
oci bv volume-group-backup create --volume-group-id ocid1.volumegroup.oc1.phx.<unique_ID>
For example:
oci bv volume-group-backup get --volume-group-backup-id ocid1.volumegroupbackup.oc1.phx.<unique_ID>
You can only update the display name for the volume group backup.
For example:
oci bv volume-group-backup update --volume-group-backup-id ocid1.volumegroupbackup.oc1.phx.<unique_ID> -
-display-name "new display name"
When you delete a volume group backup, all volume backups in the group are deleted.
For example:
oci bv volume-group-backup delete --volume-group-backup-id ocid1.volumegroupbackup.oc1.phx.<unique_ID>
l ListVolumeGroups
l CreateVolumeGroup
l DeleteVolumeGroup
l GetVolumeGroup
l UpdateVolumeGroup
Use the following operations for working with volume group backups:
l ListVolumeGroupBackups
l CreateVolumeGroupBackup
l DeleteVolumeGroupBackup
l GetVolumeGroupBackup
l UpdateVolumeGroupBackup
Creating a Volume
You can create a volume using Block Volume.
Warning
For administrators: The policy in Let volume admins manage block volumes, backups, and
volume groups lets the specified group do everything with block volumes and backups.
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
Monitoring Resources
You can monitor the health, capacity, and performance of your Oracle Cloud Infrastructure
resources by using metrics, alarms, and notifications. For more information, see Monitoring
Overview and Notifications Overview.
Tagging Resources
You can apply tags to your resources to help you organize them according to your business
needs. You can apply tags at the time you create a resource, or you can update the resource
later with the desired tags. For general information about applying tags, see Resource Tags.
l CreateVolume
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.
Attaching a Volume
You can attach a volume to an instance in order to expand the available storage on the
instance. If you specify iSCSI as the volume attachment type, you must also connect and
mount the volume from the instance for the volume to be usable. For more information, see
Volume Attachment Types and Connecting to a Volume.
You can attach volumes to more than one instance at a time, see Attaching a Volume to
Multiple Instances. To prevent data corruption from uncontrolled read/write operations with
multiple instance volume attachments you must install and configure a clustered file system
before you can use the volume, see Configuring Multiple Instance Volume Attachments with
Read/Write Access for more information.
Note
For administrators: The policy in Let users launch Compute instances includes the ability to
attach/detach existing block volumes. The policy in Let volume admins manage block
volumes, backups, and volume groups lets the specified group do everything with block
volumes and backups, but not launch instances.
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
Tip
l AttachVolume
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.
l Creating partitions.
l Creating file systems.
l Mounting file systems.
l Specifying options in the /etc/fstab file to ensure that volumes are mounted properly
when automatically mounting volumes on instance boot. For more information, see
fstab Options for Block Volumes Using Consistent Device Paths.
When you use consistent device paths on compatible Linux-based instances, the boot volume's
device path is:
/dev/oracleoci/oraclevda
Note
Consistent device paths are supported on instances when all of the following things are true:
For instances launched using the image OCID or an existing boot volume, if the source image
supports consistent device paths, the instance supports device paths.
Consistent device paths are not supported on Linux-based partner images or custom images
that are created from other sources. This feature does not apply to Windows-based images.
Important
You select a device path when you attach a block volume to an instance.
If you specify a device path, the path appears in the Attached Block Volumes list for an
instance, in the Device Path field. An example is shown in the following screenshot.
Use the following sample commands to perform various configuration tasks on the attached
volume. Commands are provided for volumes that use consistent device paths and for
volumes that don't.
This topic describes how to attach block volumes as shareable, along with the limits and
considerations for this feature.
See Volume Access Types for more information about the available access type options. For
attaching volumes to single instances, see Attaching a Volume.
can't attach it to another instance until you detach it from the first instance. You can
then reattach it to both the first and second instances as read/write shareable.
l You can't delete a block volume until it has been detached from all instances it was
attached to. When viewing the instances attached to the block volume from the
Resources section of the Volume Details page, you should note that only instances in
the selected compartment will be displayed. You may need to change the compartment
to list additional instances that are attached to the volume.
l You can attach a block volume as read/write shareable or read-only shareable up to a
maximum of eight instances.
l Block volumes attached as read-only are configured as shareable by default.
l Performance characteristics described in Block Volume Performance are per volume, so
when a block volume is attached to multiple instances the performance is shared across
all the attached instances.
You can see an sample walkthrough of scenario using OCFS2 described in Using the Multiple-
Instance Attach Block Volume Feature to Create a Shared File System on Oracle Cloud
Infrastructure. The summary of the required steps for this scenario are:
For administrators: The policy in Let users launch Compute instances includes the ability to
attach/detach existing block volumes. The policy in Let volume admins manage block
volumes, backups, and volume groups lets the specified group do everything with block
volumes and backups, but not launch instances.
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
Tip
10. For paravirtualized volume attachments on virtual machine (VM) instances, you can
optionally encrypt data that is transferred between the instance and the Block Volume
service storage servers. To do this, select the Use in-transit encryption check box. If
you configured the volume to use an encryption key that you manage using the Vault
service, this key is used for in-transit encryption. Otherwise, the Oracle-provided
encryption key is used. See Block Volume Encryption for more information.
11. Click Attach.
When the volume's icon no longer lists it as Attaching, if the attachment type is
Paravirtualized, you can use the volume. If the attachment type is iSCSI, you need to
connect to the volume first. For more information, see Connecting to a Volume.
On Linux-based instances, if you want to automatically mount volumes on instance boot,
you need to set some specific options in the /etc/fstab file, or the instance may fail to
launch. This applies to both iSCSI and paravirtualized attachment types. For volumes
using consistent device paths, see fstab Options for Block Volumes Using Consistent
Device Paths. For all other volumes, see Traditional fstab Options.
To attach a volume to multiple instances from the Block Volume details page
1. Open the navigation menu. Under Core Infrastructure, go to Block Storage and
click Block Volumes.
2. In the Block Volumes list, click the block volume that you want to attach to an
instance.
3. In the Resources section, click Attached Instances.
4. Click Attach to Instance.
5. Select the volume attachment type, iSCSI or Paravirtualized.
For more information, see Volume Attachment Types.
6. Select the volume access type. Select Read/Write-Shareable if you want to enable
read/write attachments to multiple instances or Read-only-Shareable for read-only
attachments to multiple instances.
For more information, see Volume Access Types.
7. In the Choose Instance drop-down list, select the instance. Click Change
Compartment if the instance is in a different compartment than the default one listed.
If you want to specify the instance using the OCID, select the ENTER INSTANCE OCID
option and then copy the OCID in the textbox.
8. If the instance supports consistent device paths select a path from the Device Path
drop-down list when attaching. This is required and enables you to specify a device path
for the volume attachment that remains consistent between instance reboots.
For more information about this feature and the instances that support it, see
Connecting to Volumes With Consistent Device Paths
Tip
9. For paravirtualized volume attachments on virtual machine (VM) instances, you can
optionally encrypt data that is transferred between the instance and the Block Volume
service storage servers. To do this, select the Use in-transit encryption check box. If
you configured the volume to use an encryption key that you manage using the Vault
service, this key is used for in-transit encryption. Otherwise, the Oracle-provided
encryption key is used. See Block Volume Encryption for more information.
10. Click Attach.
When the volume's icon no longer lists it as Attaching, if the attachment type is
Paravirtualized, you can use the volume. If the attachment type is iSCSI, you need to
connect to the volume first. For more information, see Connecting to a Volume.
On Linux-based instances, if you want to automatically mount volumes on instance boot,
you need to set some specific options in the /etc/fstab file, or the instance may fail to
launch. This applies to both iSCSI and paravirtualized attachment types. For volumes
using consistent device paths, see fstab Options for Block Volumes Using Consistent
Device Paths. For all other volumes, see Traditional fstab Options.
To view the instances attached to a volume from the Volume details page
1. Open the navigation menu. Under Core Infrastructure, go to Block Storage and
click Block Volumes.
2. In the Block Volumes list, click the block volume that you want to view the attached
instances for.
3. In the Resources section, click Attached Instances.
All the attached instances in the selected compartment will be displayed in the list. To view
attached instances in other compartments, change the compartment in the COMPARTMENT
drop down list.
To view the volumes attached to an instance from the Instance details page
1. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Instances.
2. In the Instances list, click the instance that you want to view the attached volumes for.
3. In the Resources section, click Attached Block Volumes.
All the block volumes attached to the instance will be displayed in the list, regardless of the
compartment the block volumes are in.
For example:
oci compute volume-attachment attach --instance-id ocid1.instance.oc1..<unique_ID> --type iscsi --
volume-id ocid1.volume.oc1..<unique_ID> --read-only false --is-shareable true
For example:
oci compute volume-attachment attach --compartment-id ocid1.compartment.oc1..<unique_ID> --volume-id
ocid1.volume.oc1..<unique_ID>
Note
l AttachVolume
Set the isShareable attribute of AttachVolumeDetails to true.
l GetVolumeAttachment
l ListVolumeAttachments
The ListVolumeAttachments operation will only return the attached instances that are
in compartment you specify. You need to run this operation for every compartment that
may contain instances that are attached to the specified volume.
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.
Additional Resources
See the following links for example deployments of shared file systems on Oracle Cloud
Infrastructure.
Connecting to a Volume
For volumes attached with Paravirtualized as the volume attachment type, you do not need to
perform any additional steps after Attaching a Volume, the volumes are connected
automatically. However, for Linux-based images, if you want to mount these volumes on
instance boot, you need to perform additional configuration steps. If you specified a device
path when you attached the volume, see fstab Options for Block Volumes Using Consistent
Device Paths. If you did not specify a device path or if your instance was created from an
image that does not support device paths, see Traditional fstab Options.
For volumes attached with iSCSI as the volume attachment type, you need to connect and
mount the volume from the instance for the volume to be usable. For more information about
attachment type options, see Volume Attachment Types. In order to connect the volume, you
must first attach the volume to the instance, see Attaching a Volume.
Connecting a volume to an instance does not require a specific IAM policy. However, you may
need permission to run the necessary commands on the instance's guest OS. Contact your
system administrator for more information.
Prerequisites
You must attach the volume to the instance before you can connect the volume to the
instance's guest OS. For details, see Attaching a Volume.
l iSCSI IP Address
l iSCSI Port numbers
l CHAP credentials (if you enabled CHAP)
l IQN
The Console provides the commands required to configure, authenticate, and log on to iSCSI.
7. You can now format (if needed) and mount the volume. To get a list of mountable iSCSI
devices on the instance, run the following command:
fdisk -l
Tip
Warning
1. Use the Console to obtain the iSCSI data you need to connect the volume:
a. Log on to Oracle Cloud Infrastructure.
b. Open the navigation menu. Under Core Infrastructure, go to Compute and
click Instances.
c. Click your instance's name to display the instance details.
d. In the Resources section on the Instance Details page, click Attached Block
Volumes to view the attached block volume.
e. Click the Actions icon (three dots) next to the volume you're interested in, and
then click iSCSI Commands and Information.
The iSCSI Commands and Information dialog box displays your volume’s IP
address and port, which you’ll need to know later in this procedure.
2. Log in to your instance using a Remote Desktop client.
3. On your Windows instance, open the iSCSI Initiator. The steps to open the iSCSI
Initiator may vary depending on the version of Windows.
For example: Open Server Manager, click Tools, and then select iSCSI Initiator.
4. In the iSCSI Initiator Properties dialog box, click the Discovery tab, and then click
Discover Portal.
5. Enter the block volume IP Address and Port, and then click OK.
6. Click the Targets tab.
7. Under Discovered targets, select the volume IQN.
8. Click Connect.
9. Make sure that the Add this connection to the list of favorite targets check box is
selected, and then click OK.
10. You can now format (if needed) and mount the volume. To view a list of mountable
iSCSI devices on your instance, in Server Manager, click File and Storage
Services, and then click Disks.
The disk is displayed in the list.
Note
Prerequisites
Before using a consistent device path, you should confirm that the instance supports
consistent device paths and is correctly configured.
To verify that the volume is attached to a supported instance, connect to the instance and run
the following command:
ll /dev/oracleoci/oraclevd*
If you don't see this output and instead see the following error message:
cannot access /dev/oracleoci/oraclevd*: No such file or directory
there may be a problem with the instance configuration for device paths. For assistance with
this, contact Support.
By default, the /etc/fstab file is processed before the initiator starts. To configure the mount
process to initiate before the volumes are mounted, specify the _netdev option on each line of
the /etc/fstab file.
When you create a custom image of an instance where the volumes, excluding the root
volume, are listed in the /etc/fstab file, instances will fail to launch from the custom image.
To prevent this issue, specify the nofail option in the /etc/fstab file.
In the example scenario with three volumes, the /etc/fstab file entries for the volumes with
the _netdev and nofail options are as follows:
/dev/oracleoci/oraclevdb /mnt/vol1 xfs defaults,_netdev,nofail 0 2
/dev/oracleoci/oraclevdc /mnt/vol2 xfs defaults,_netdev,nofail 0 2
/dev/oracleoci/oraclevdd /mnt/vol3 xfs defaults,_netdev,nofail 0 2
After you have updated the /etc/fstab file, use the following command to mount the
volumes:
bash-4.2$ sudo mount -a
Reboot the instance to confirm that the volumes are mounted properly on reboot with the
following command:
bash-4.2$ sudo reboot
If the instance fails to reboot after you update the /etc/fstab file, you may need to undo the
changes to the /etc/fstab file. To update the file, first connect to the serial console for the
instance. When you have access to the instance using the serial console connection, you can
remove, comment out, or fix the changes that you made to the /etc/fstab file.
Note
Volume UUIDs
On Linux operating systems, the order in which volumes are attached is non-deterministic, so
it can change with each reboot. If you refer to a volume using the device name, such as
/dev/sdb, and you have more than one non-root volume, you can't guarantee that the volume
you intend to mount for a specific device name will be the volume mounted.
To prevent this issue, specify the volume UUID in the /etc/fstab file instead of the device
name. When you use the UUID, the mount process matches the UUID in the superblock with
the mount point specified in the /etc/fstab file. This process guarantees that the same
volume is always mounted to the same mount point.
3. Run the following command to use the blkid utility to get the UUIDs for the volumes:
sudo blkid
The root volume in this output is /dev/sda*. The additional remote volumes are:
l /dev/sdb
l /dev/sdc
l /dev/sdd
By default, the /etc/fstab file is processed before the initiator starts. To configure the mount
process to initiate before the volumes are mounted, specify the _netdev option on each line of
the /etc/fstab file.
When you create a custom image of an instance where the volumes, excluding the root
volume, are listed in the /etc/fstab file, instances will fail to launch from the custom image.
To prevent this issue, specify the nofail option in the /etc/fstab file.
In the example scenario with three volumes, the /etc/fstab file entries for the volumes with
the _netdev and nofail options are as follows:
UUID=699a776a-3d8d-4c88-8f46-209101f318b6 /mnt/vol1 xfs defaults,_netdev,nofail 0 2
UUID=ba0ac1d3-58cf-4ff0-bd28-f2df532f7de9 /mnt/vol2 xfs defaults,_netdev,nofail 0 2
UUID=85566369-7148-4ffc-bf97-50954cae7854 /mnt/vol3 xfs defaults,_netdev,nofail 0 2
After you have updated the /etc/fstab file, use the following command to mount the
volumes:
bash-4.2$ sudo mount -a
Reboot the instance to confirm that the volumes are mounted properly on reboot with the
following command:
bash-4.2$ sudo reboot
If the instance fails to reboot after you update the /etc/fstab file, you may need to undo the
changes to the /etc/fstab file. To update the file, first connect to the serial console for the
instance. When you have access to the instance using the serial console connection, you can
remove, comment out, or fix the changes that you made to the /etc/fstab file.
Listing Volumes
You can list all Block Volume volumes in a specific compartment, as well as detailed
information on a single volume.
For administrators: The policy in Let users launch Compute instances includes the ability to
list volumes. The policy in Let volume admins manage block volumes, backups, and volume
groups lets the specified group do everything with block volumes and backups, but not launch
instances.
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
List Volumes:
l ListVolumes
l GetVolume
For administrators: The policy in Let users launch Compute instances includes the ability to
list volume attachments. The policy in Let volume admins manage block volumes, backups,
and volume groups lets the specified group do everything with block volumes and backups,
but not launch instances.
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
List Attachments:
l ListVolumeAttachments
l GetVolumeAttachment
For administrators: The policy in Let users launch Compute instances includes the ability to
list volume attachments. The policy in Let volume admins manage block volumes, backups,
and volume groups lets the specified group do everything with block volumes and backups,
but not launch instances.
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
l ListBootVolumeAttachments
l GetBootVolumeAttachment
Renaming a Volume
You can use the API to change the display name of a Block Volume volume.
Warning
For administrators: The policy in Let users launch Compute instances includes the ability to
rename block volumes. The policy in Let volume admins manage block volumes, backups, and
volume groups lets the specified group do everything with block volumes and backups, but not
launch instances.
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
l UpdateVolume
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.
For administrators: The policy in Let users launch Compute instances includes the ability to
attach/detach existing block volumes. The policy in Let volume admins manage block
volumes, backups, and volume groups lets the specified group do everything with block
volumes and backups, but not launch instances.
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
l Resizing a Volume
l Rescanning the Disk for a Block Volume or Boot VolumeThe Oracle Cloud Infrastructure
Block Volume service lets you expand the size of block volumes and boot volumes while
they are online and attached to instances, for more information, see Online Resizing of
Block Volumes Using the Console. After the volume is provisioned, you need to run
commands to rescan the disk, so that the operating system identifies the expanded
volume size. You will need to run different rescan commands depending on the
operating system of the attached instance. This topic describes some procedures you
can use to rescan the disk. Required IAM PolicyRescanning the disk does not require a
specific IAM policy. However, you may need permission to run the necessary
commands on the instance's guest OS. Contact your system administrator for more
information.Rescanning the Disk for Volumes Attached to Linux-Based InstancesFor
volumes attached to Linux-based instances, run the following commands rescan the disk
for a block volume: sudo dd iflag=direct if=/dev/<device_name> of=/dev/null count=1
echo "1" | sudo tee /sys/class/block/<device_name>/device/rescan These commands
are also displayed in the dialog that opens after you click Save Changes in the Edit Size
or Performance dialog, and you can copy them from that dialog. Next StepsAfter you've
rescanned the disk, you need to extend the partition. See Extending the Partition for a
Block Volume on a Linux-Based Image for block volumes, see Extending the Root
Partition on a Linux-Based Image for boot volumes.Rescanning the Disk for Volumes
Attached to Windows Instances Using Disk Management or diskpartFor volumes
formatted as FAT32 or NTFS, you can rescan the disk using the Windows interface, in
Disk Management, or you can use the diskpart utility's rescan command from the
command line. Rescanning the disk using the command line with DISKPARTOpen a
command prompt as administrator on the instance.Run the following command to start
the diskpart utility:diskpartAt the DISKPART prompt, run the following
command:rescanRescanning the disk using the Windows interfaceOpen the Disk
Management system utility on the instance.Click Action, and then click Rescan Disks.
For detailed instructions and more information about both of these procedures, see
Update disk information. Using CygwinFor volumes formatted with a non-native
Windows file system, such as volumes formatted using Oracle Automatic Storage
Management (Oracle ASM), you can't use the Windows interface or the diskpart utitily.
Instead, you can use the dd process from a Cygwin terminal to rescan the disk. You can
also use this for native Windows file systems. For more information, see Cygwin.Next
StepsAfter you've rescanned the disk, you need to extend the partition. See Extending
the Partition for a Block Volume on a Windows-Based Image for block volumes, see
Extending the System Partition on a Windows-Based Image for boot volumes.
l Extending the Partition for a Block Volume and Extending the Partition for a Boot Volume
Changing the Volume Performance for Block Volumes and Boot Volumes
The elastic performance feature of the Block Volume service allows you to dynamically
change the volume performance, see Block Volume Elastic Performance for more information.
You can change volume performance for your block volumes and boot volumes while they are
online, without any downtime, see Changing the Performance of a Volume. For specific
information about this task in the Console, see Using the Console.
Resizing a Volume
The Oracle Cloud Infrastructure Block Volume service lets you expand the size of block
volumes and boot volumes. You have several options to increase the size of your volumes:
l Expand an existing volume in place with online resizing. See Online Resizing of Block
Volumes Using the Console for the steps to do this.
l Restore from a volume backup to a larger volume. See Restoring a Backup to a New
Volume and Restoring a Boot Volume.
l Clone an existing volume to a new, larger volume. See Cloning a Volume and Cloning a
Boot Volume.
l Expand an existing volume in place with offline resizing. See Offline Resizing of Block
Volumes Using the Console for the steps to do this.
For more information about the Block Volume service, see the Block Volume FAQ.
You can only increase the size of the volume, you cannot decrease the size.
Warning
Note
For administrators: The policy in Let users launch Compute instances includes the ability to
attach/detach existing block volumes. The policy in Let volume admins manage block
volumes, backups, and volume groups lets the specified group do everything with block
volumes and backups, but not launch instances.
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
1. Open the navigation menu. Under Core Infrastructure, go to Block Storage and
click Block Volumes.
2. In the Block Volumes list, click the block volume you want to resize.
3. Click Edit Size or Performance.
4. Specify the new size in VOLUME SIZE (IN GB). You must specify a larger value than
the block volume's current size.
5. Click Save Changes.
6. Rescan the disk, see Rescanning the Disk for Volumes Attached to Windows Instances.
7. Extend the partition, see Extending the Partition for a Block Volume.
Whenever you detach and reattach volumes, there are complexities and risks for both Linux-
based and Windows-based instances. This applies to both paravirtualized and iSCSI
attachment types. You should keep the following in mind when resizing volumes:
l When you reattach a volume to an instance after resizing, if you are not using consistent
device paths, or the instance does not support consistent device paths, device order and
path may change. If you are using a tool such as Logical Volume Manager (LVM), you
may need to fix the device mappings. For more information about consistent device
paths, see Connecting to Volumes With Consistent Device Paths.
l When you detach and then reattach an iSCSI-attached volume to an instance, the
volume's IP address will increment.
l Before you resize a volume, you should create a full backup of the volume.
Rescanning the disk does not require a specific IAM policy. However, you may need
permission to run the necessary commands on the instance's guest OS. Contact your system
For volumes attached to Linux-based instances, run the following commands rescan the disk
for a block volume:
sudo dd iflag=direct if=/dev/<device_name> of=/dev/null count=1
echo "1" | sudo tee /sys/class/block/<device_name>/device/rescan
These commands are also displayed in the dialog that opens after you click Save Changes in
the Edit Size or Performance dialog, and you can copy them from that dialog.
NEXT S TEPS
After you've rescanned the disk, you need to extend the partition. See Extending the Partition
for a Block Volume on a Linux-Based Image for block volumes, see Extending the Root
Partition on a Linux-Based Image for boot volumes.
For volumes formatted as FAT32 or NTFS, you can rescan the disk using the Windows
interface, in Disk Management, or you can use the diskpart utility's rescan command from
the command line.
For detailed instructions and more information about both of these procedures, see Update
disk information.
USING CYGWIN
For volumes formatted with a non-native Windows file system, such as volumes formatted
using Oracle Automatic Storage Management (Oracle ASM), you can't use the Windows
interface or the diskpart utitily. Instead, you can use the dd process from a Cygwin terminal
to rescan the disk. You can also use this for native Windows file systems. For more
information, see Cygwin.
NEXT S TEPS
After you've rescanned the disk, you need to extend the partition. See Extending the Partition
for a Block Volume on a Windows-Based Image for block volumes, see Extending the System
Partition on a Windows-Based Image for boot volumes.
Note
Extending a partition on an instance does not require a specific IAM policy. However, you may
need permission to run the necessary commands on the instance's guest OS. Contact your
system administrator for more information.
On Linux-based images, use the following steps to extend the partition for a block volume.
PREREQUISITES
After you have resized a volume, you need to attach it to an instance before you can extend
the partition and grow the file system. See Attaching a Volume and Connecting to a Volume
for more information.
Extending a partition
1. To identify the volume that you want to extend the partition for, run the following
command to list the attached block volumes:
lsblk
2. Run the following command to edit the volume's partition table with parted:
parted <volume_id>
You are then prompted to fix the error or ignore the error and continue with the current
setting. Specify the option to fix the error.
4. Run the following command to change the display units to sectors so that you can see
the precise start position for the volume:
(parted) unit s
5. Run the following command to display the current partitions in the partition table:
(parted) print
Make note of the values in the Number, Start, and File system columns for the root
partition.
6. Run the following command to remove the existing root partition:
(parted) rm <partition_number>
At the Start? prompt, specify the value from the Start column. At the File system
type? prompt, specify the value from the File system column. Specify 100% for the
End? prompt.
This command forces a rewrite of the partition table with the new partition settings that
you specified.
9. To verify that the root partition was extended, run the following command to list the
attached block volumes:
lsblk
After you extend the root partition you need to grow the file system. The steps in the following
procedure apply only to xfs file systems.
<partition_id> is the partition identifier, for example /dev/sdc1. See Checking and
Repairing an XFS File System for more information.
2. After you have confirmed that there are no more issues to repair, you need to create a
mount point to run the xfs_growfs against. To do this, create a directory and mount the
partition to that directory by running the following commands:
mkdir <directory_name>
mount <partition_id> <directory_name> -o nouuid
3. After you have created the mount point run the following command to grow the file
system:
xfs_growfs -d <directory_name>
<directory_name> is the name for the directory you created in the previous step, for
example data.
4. To verify that the file system size is correct, run the following command to display the
file system details:
df -lh
On Windows-based images, you can extend a partition using the Windows interface or from
the command line using the DISKPART utility.
The steps to extend a partition for a block volume attached to an instance running Windows
Server 2012, Windows Server 2016, or Windows Server 2019 are the same, and are described
in the following procedures.
3. At the DISKPART prompt, run the following command to display the instance's volumes:
list volume
<volume_number> is the number associated with the block volume that you want to
extend the partition for.
5. Run the following command to extend the partition:
extend size=<increased_size_in_MB>
<increased_size_in_MB> is the size in MB that you want to extend the partition to.
Warning
6. To confirm that the partition was extended, run the following command and verify that
the block volume's partition has been extended:
list volume
Backups are encrypted and stored in Oracle Cloud Infrastructure Object Storage, and can be
restored as new volumes to any availability domain within the same region they are stored.
This capability provides you with a spare copy of a volume and gives you the ability to
successfully complete disaster recovery within the same region.
There are two ways you can initiate a backup, either by manually starting the backup, or by
assigning a policy which defines a set backup schedule.
Manual Backups
These are on-demand one-off backups that you can launch immediately by following the steps
described in Backing Up a Volume. When launching a manual backup, you can specify whether
an incremental or a full backup should be performed. See Volume Backup Types for more
information about backup types.
Policy-Based Backups
These are automated scheduled backups as defined by the backup policy assigned to the
volume.
l Oracle defined: Predefined backup policies that have a set backup frequency and
retention period. You cannot modify these policies. For more information, see Oracle
Defined Backup Policies.
l User defined: Custom backup policies that you create and configure schedules and
retention periods for. You can also enable scheduled cross-region automated backups
with user defined policies, see Scheduling Volume Backup Copies Across Regions. For
more information, see User Defined Backup Policies.
Tags
When a volume backup is created, the source volume's tags are automatically included in the
volume backup. This also includes volumes with custom backup policies applied to create
backups on a schedule. Source volume tags are automatically assigned to all backups when
they are created. You can also apply additional tags to volume backups as needed.
When a volume backup is copied to a new region, tags are also automatically copied with the
volume backup. When the volume is restored from a backup, the volume is restored with the
source volume's tags.
l Incremental: This backup type includes only the changes since the last backup.
l Full: This backup type includes all changes since the volume was created.
You can restore a volume from any of your incremental or full volume backups. Both backup
types enable you to restore the full volume contents to the point-in-time snapshot of the
volume when the backup was taken. You don't need to keep the initial full backup or
subsequent incremental backups in the backup chain and restore them in sequence, you only
need to keep the backups taken for the times you care about.
Backup Details
For incremental backups, they are a record of all the changes since the last backup. If the first
backup on a volume is created as incremental, it is effectively a full backup. For full backups,
they are a record of all the changes since the volume was created.
For example, in a scenario where you create a 16 TB block volume, modify 40 GB on the
volume, and then launch a full backup of the volume, upon completion, the volume backup
size is 40 GB. If you then modify an additional 4 GB and create an incremental backup, the
unique size of the incremental backup will be 4 GB. If the full backup is deleted, the
incremental backup will retain the full 44 GB necessary to restore the volume contents. In this
example, if there was a third incremental backup of non-overlapping blocks, with a size of 1
GB, created after the second incremental backup, and then the full backup is deleted, the third
backup would stay at a 1 GB size, and the second incremental backup size would be updated
to 44 GB. The blocks are accounted for in the earliest backup that references them.
Note
l Needing to create multiple copies of the same volume. Backups are highly useful in
cases where you need to create many instances with many volumes that need to have
the same data formation.
l Taking a snapshot of your work that you can restore to a new volume at a later time.
l Ensuring you have a spare copy of your volume in case something goes wrong with your
primary copy.
Volume backup size may be larger than the current volume usage. Some of the reasons for
this could include the following:
l Any part of a volume that has been written to is considered initialized, so will always be
part of a volume backup.
l Many operating systems write or zero out the content, which results in these blocks
marked as used. The Block Volume service considers these blocks updated and includes
them in the volume backup.
l Volume backups also include metadata, which can be up to 1 GB in additional data. For
example, in a full backup of a 256 GB Windows boot disk, you may see a backup size of
257 GB, which includes an additional 1 GB of metadata.
You can also enable scheduled cross-region automated backups with user defined policies, see
Scheduling Volume Backup Copies Across Regions.
To copy volume backups between regions, you must have permission to read and copy
volume backups in the source region, and permission to create volume backups in the
destination region. For more information see Required IAM Policy.
Once you have copied the volume backup to the new region you can then restore from that
backup by creating a new volume from the backup using the steps described in Restoring a
Backup to a New Volume.
The Oracle Cloud Infrastructure Vault service enables you to bring and manage your own keys
to use for encrypting volumes and their backups. When you create a volume backup, the
encryption key used for the volume is also used for the volume backup. When you restore the
backup to create a new volume you configure a new key, see Restoring a Backup to a New
Volume. See also Overview of Vault.
If you do not configure a volume to use the Vault service, the Block Volume service uses the
Oracle-provided encryption key instead. This applies to both encryption at-rest and in-transit
encryption.
l Before creating a backup, you should ensure that the data is consistent: Sync the file
system, unmount the file system if possible, and save your application data. Only the
data on the disk will be backed up. When creating a backup, after the backup state
changes from REQUEST_RECEIVED to CREATING, you can return to writing data to the
volume. While a backup is in progress, the volume that is being backed up cannot be
deleted.
l If you want to attach a restored volume that has the original volume attached, be aware
that some operating systems do not allow you to restore identical volumes. To resolve
this, you should change the partition IDs before restoring the volume. The steps to
change an operating system's partition ID vary by operating system. For instructions,
see your operating system's documentation.
l You should not delete the original volume until you have verified that the backup you
created of it completed successfully.
See Backing Up a Volume and Restoring a Backup to a New Volume for more information.
Volume Supported. You can back up a Supported. You can clone a volume group.
groups volume group.
For background information and steps to clone a block volume, see Cloning a Volume.
Using the CLI or REST APIs to Customize and Manage the Lifecycle of
Volume Backups
You can use the CLI, REST APIs, or the SDKs to automate, script, and manage volume backups
and their lifecycle.
Warning
This section provides basic sample CLI commands that you can use in a script, such as a cron
job run by the cron utility on Linux-based operating systems, to perform automatic backups at
specific times. For information about using the CLI, see Command Line Interface (CLI).
For example:
oci bv backup create --volume-id ocid1.volume.oc1..<unique_ID> --display-name "backup display name" --
type FULL
For example:
oci bv backup delete --volume-backup-id ocid1.volume.oc1..<unique_ID>
For example:
oci bv boot-volume-backup create --volume-id ocid1.volume.oc1..<unique_ID> --display-name "backup
display name" --type FULL
For example:
oci bv backup delete --boot-volume-backup-id ocid1.volume.oc1..<unique_ID>
For example:
oci bv volume-backup-policy-assignment create --asset-id ocid1.volume.oc1..<unique_ID> --policy-id
ocid1.volumebackuppolicy.oc1..<unique_ID>
For example:
oci bv volume-backup-policy-assignment delete --policy-assignment-id
ocid1.volumebackuppolicyassign.oc1..<unique_ID>
For example:
oci bv volume-backup-policy-assignment get-volume-backup-policy-asset-assignment --asset-id
ocid1.volume.oc1..<unique_ID>
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.
Use the following operations for working with block volume backups, boot volume backups,
and backup policies.
l CreateVolumeBackup
l DeleteVolumeBackup
l GetVolumeBackup
l ListVolumeBackups
l UpdateVolumeBackup
l CreateBootVolumeBackup
l DeleteBootVolumeBackup
l GetBootVolumeBackup
l ListBootVolumeBackups
l UpdateBootVolumeBackup
l GetVolumeBackupPolicy
l ListVolumeBackupPolicies
l CreateVolumeBackupPolicyAssignment
l DeleteVolumeBackupPolicyAssignment
l GetVolumeBackupPolicyAssetAssignment
l GetVolumeBackupPolicyAssignment
Backing Up a Volume
You can create a backup of a volume using Block Volume. Volume backups are point-in-time
snapshots of volume data. For more information about volume backups, see Overview of
Block Volume Backups.
For information to help you decide whether to create a backup or a clone of a boot volume,
see Differences Between Block Volume Backups and Clones.
Note
Warning
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: The policy in Let volume admins manage block volumes, backups, and
volume groups lets the specified group do everything with block volumes and backups. The
policy in Let volume backup admins manage only backups further restricts access to just
creating and managing backups.
Tip
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
1. Open the navigation menu. Under Core Infrastructure, go to Block Storage and
click Block Volumes.
2. Click the block volume that you want to create a backup for.
3. Click Create Manual Backup.
4. Enter a name for the backup.
5. Select the backup type, either incremental or full. See Volume Backup Types for
information about backup types.
6. Optionally, you can apply 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 Backup.
The backup will be completed once its icon no longer lists it as CREATING in the
volume list.
l CreateVolumeBackup
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.
For more information about backups, see Overview of Block Volume Backups and Restoring a
Backup to a New Volume.
Policy-Based Backups
The Oracle Cloud Infrastructure Block Volume service provides you with the capability to
perform volume backups automatically on a schedule and retain them based on the selected
backup policy.
With user defined policies, you can also enable scheduled cross-region backups, so that
scheduled volume backups are automatically copied to a second region, see Scheduling
Volume Backup Copies Across Regions.
These features allow you to adhere to your data compliance and regulatory requirements.
Warning
Volume backups are point-in-time snapshots of volume data. For more information about
volume backups, see Overview of Block Volume Backups.
l User defined: Custom backup policies that you create and configure schedules for.
l Oracle defined: Predefined backup policies that have a set backup frequency and
retention period. You cannot modify these policies.
Oracle Cloud Infrastructure enables you to customize your backup schedules with user defined
policies. These are backup policies that you define the backup frequency and retention period
for. There are two parts to user defined backup policies, the backup policy itself, and then one
or more schedules in the policy.
To get started with user defined backup policies, you need to first create the backup policy,
see To create a user defined backup policy. After this step, you have an empty backup policy,
so the next step is to define and add schedules to the policy.
S CHEDULES
Schedules define the backup frequency and retention period for a user defined backup policy,
just like Oracle defined backup policies. The difference is that you can customize the
schedules associated with user defined policies. This gives you control over the backup
frequency and retention period.
When defining a schedule for a user defined backup policy, the first thing you configure is the
schedule type, this specifies the backup frequency. Oracle Cloud Infrastructure provides the
following schedule types:
l Daily: Backups are generated daily. You specify the hour of the day for the backup.
l Weekly: Backups are generated weekly. You specify the day of the week, and the hour
of that day for the backup.
l Monthly: Backups are generated monthly. You specify the day of the month, and the
hour of that day for the backup.
l Yearly: Backups are generated yearly. You specify the month, the day of that month,
and the hour of that day for the backup.
l Retention time: The amount of time to keep the backup, in days, weeks, months, or
years. The time period is based the schedule type.
l Backup type Options are full or incremental, see Volume Backup Types for more
information.
l Timezone The time zone to use for the backup schedule. Options are UTC or the
regional data center time zone.
For more information, see To add a schedule to a user defined backup policy.
You can also edit or remove schedules for a user defined policy at any time, see To edit a
schedule for a user defined backup policy and To delete a schedule for a user defined backup
policy.
You can create a new backup policy by duplicating any of the existing backup policies.
If one of the Oracle defined policies is close to meeting your volume backup requirements, but
with some changes, you can create a new backup policy by duplicating the Oracle defined
policy. This creates a new user defined backup policy with schedules already assigned,
enabling you to use the Oracle defined policy's settings as a starting point to save time and
simplify the process.
You can also duplicate an existing user defined policy. For more information, see To duplicate
a backup policy. You can then add, edit, or delete schedules for the new backup policy.
The Block Volume service enables you to copy volume backups from one region to another for
business continuity and disaster recovery scenarios, for more information, see Copying Block
Volume Backups Across Regions. With user-defined policies, you can automate this process,
so that volume backups are copied to another region on a schedule. Enabling the automatic
copying of scheduled volume backups is only supported with user-defined policies, so if you
need to use this feature for a volume currently configured with an Oracle defined policy, you
need to duplicate the policy and then enable cross region copy. The volume backup copy in the
target region has the same retention period as the volume backup in the source region
Once this feature is enabled, your bill will include charges for storing volume backups in both
the source region and the destination region. You may also see an increase in network costs.
Note
REGIONS PAIRS
When you enable cross region copy for a backup policy, the target region is based on the
source region for the backup and cannot be changed. The following table lists the source and
target region pairs for cross region copy. To copy a volume backup to a region not paired with
the backup's source region, you must manually copy the volume backup, see Copying a
Volume Backup Between Regions.
Note
There are three Oracle defined backup policies, Bronze, Silver, and Gold. Each backup policy
is comprised of schedules with a set backup frequency and a retention period that you cannot
modify. If the backup policy settings for Oracle defined policies don't meet your
requirements, you should use User Defined Backup Policies instead. With user defined backup
policies you define and control the schedules. You can also enable the automatic copying of
volume backups to a second region, which is not supported with Oracle defined policies.
BRONZE POLICY
The bronze policy includes monthly incremental backups, run on the first day of the month.
These backups are retained for twelve months. This policy also includes a full backup, run
yearly on January 1st. Full backups are retained for five years.
S ILVER POLICY
The silver policy includes weekly incremental backups that run on Sunday. These backups are
retained for four weeks. This policy also includes monthly incremental backups, run on the
first day of the month and are retained for twelve months. Also includes a full backup, run
yearly on January 1st. Full backups are retained for five years.
GOLD POLICY
The gold policy includes daily incremental backups. These backups are retained for seven
days. This policy also includes weekly incremental backups that run on Sunday and are
retained for four weeks. Also includes monthly incremental backups, run on the first day of
the month, retained for twelve months, and a full backup, run yearly on January 1st. Full
backups are retained for five years.
There are two types of tasks when working with backup policies:
The linked sections listed above provide information for working with backup policies using
the Console, CLI, and REST APIs.
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.
Important
For administrators: The policy in Let volume admins manage block volumes, backups, and
volume groups lets the specified group do everything with block volumes and backups. The
policy in Let volume backup admins manage only backups further restricts access to just
creating and managing backups.
Tip
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
TAGGING RESOURCES
You can apply tags to your resources to help you organize them according to your business
needs. You can update the resource later with the desired tags. For general information about
applying tags, see Resource Tags.
You can use the Console to create and update user defined backup policies.
3. In Schedules, for the schedule you want to delete, click the Actions icon (three dots),
and then click Delete.
4. Click Delete in the confirmation dialog.
For information about using the CLI, see Command Line Interface (CLI).
For example:
oci bv volume-backup-policy create --compartment-id ocid1.compartment.oc1..<unique_ID> --schedules
file//~/input.json
For example:
oci bv volume-backup-policy list --compartment-id ocid1.compartment.oc1..<unique_ID>
For example:
oci bv volume-backup-policy get --backup-policy-id ocid1.volumebackuppolicy.oc1.phx.<unique_ID>
For example:
oci bv volume-backup-policy update --backup-policy-id ocid1.volumebackuppolicy.oc1.phx.<unique_ID> --
display-name "new display name"
For example:
oci bv volume-backup-policy update --volume-group-id ocid1.volumebackuppolicy.oc1.phx.<unique_ID> --
schedules file//~/input.json
You can only delete a user defined backup policy if it is not assigned to any volumes. You
cannot delete Oracle defined backup policies.
For example:
oci bv volume-backup-policy delete --backup-policy-id ocid1.volumebackuppolicy.oc1.phx.<unique_ID>
l CreateVolumeBackupPolicy
l DeleteVolumeBackupPolicy
l UpdateVolumeBackupPolicy
l ListVolumeBackupPolicies
l GetVolumeBackupPolicy
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.
For more information about backups, see Overview of Block Volume Backups and Restoring a
Backup to a New Volume.
You can use the Console to assign, change, or remove both user defined and Oracle defined
backup policies for existing volumes.
For information about using the CLI, see Command Line Interface (CLI).
Use the following operations to work with volume backup policy assignments to volumes:
For example:
oci bv volume-backup-policy-assignment create --asset-id ocid1.volume.oc1..<unique_ID> --policy-id
ocid1.volumebackuppolicy.oc1..<unique_ID>
For example:
oci bv volume-backup-policy-assignment get-volume-backup-policy-asset-assignment --asset-id
ocid1.volume.oc1..<unique_ID>
For example:
oci bv volume-backup-policy-assignment get --policy-assignment-id
ocid1.volumebackuppolicyassignment.oc1.phx.<unique_ID>
You can only delete a user defined backup policy if it is not assigned to any volumes. You
cannot delete Oracle defined backup policies.
For example:
oci bv volume-backup-policy-assignment delete ----policy-assignment-id
ocid1.volumebackuppolicyassignment.oc1.phx.<unique_ID>
l CreateVolumeBackupPolicyAssignment
l DeleteVolumeBackupPolicyAssignment
l GetVolumeBackupPolicyAssetAssignment
l GetVolumeBackupPolicyAssignment
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.
For more information about backups, see Overview of Block Volume Backups and Restoring a
Backup to a New Volume.
You can restore a volume from any of your incremental or full volume backups. Both backup
types enable you to restore the full volume contents to the point-in-time snapshot of the
volume when the backup was taken. You don't need to keep the initial full backup or
subsequent incremental backups in the backup chain and restore them in sequence, you only
need to keep the backups taken for the times you care about. See Volume Backup Types for
information about full and incremental backup types.
Warning
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: The policy in Let volume admins manage block volumes, backups, and
volume groups lets the specified group do everything with block volumes and backups.
Tip
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
1. Open the navigation menu. Under Block Storage, click Block Volume Backups.
A list of the block volume backups in the compartment you're viewing is displayed. If
you don’t see the one you're looking for, make sure you’re viewing the correct
compartment (select from the list on the left side of the page).
2. Click the Actions icon (three dots) for the block volume backup you want to restore.
3. Click Create Block Volume.
4. Enter a name for the block volume and choose the availability domain in which you want
to restore it.
5. You can restore a block volume backup to a larger volume size. To do this, check
Custom Block Volume Size (GB), and then specify the new size. You can only
increase the size of the volume, you cannot decrease the size. If you restore the block
volume backup to a larger size volume, you need to extend the volume's partition, see
Extending the Partition for a Block Volume for more information.
6. Optionally, you can select the appropriate backup policy for your requirements. See
Policy-Based Backups for more information about backup policies.
7. Optionally, you can encrypt the data in this volume using your own Vault encryption
key. To use Vault for your encryption needs, select the Encrypt using Vault check
box. Then, select the Vault compartment and Vault that contain the master
encryption key you want to use. Also select the Master encryption key
compartment and Master encryption key. For more information about encryption,
see Overview of Vault.
8. Optionally, you can apply 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.
9. Click Create.
The volume will be ready to attach once its icon no longer lists it as PROVISIONING in
the volume list. For more information, see Attaching a Volume.
Warning
The API used to restore a backup is CreateVolume. The API has an optional volumeBackupId
parameter that you can use to define the backup from which the data should be restored on
the newly created volume. For details, see CreateVolumeDetails Reference.
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.
For more information about backups, see Overview of Block Volume Backups and Backing Up
a Volume.
Note
Warning
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: The first two statements listed in the Let volume admins manage block
volumes, backups, and volume groups policy lets the specified group do everything with block
volumes and backups with the exception of copying volume backups across regions. The
aggregate resource type volume-family does not include the VOLUME_BACKUP_COPY
permission, so to enable copying volume backups across regions you need to ensure that you
include the third statement in that policy, which is:
Allow group VolumeAdmins to use volume-backups in tenancy where request.permission='VOLUME_BACKUP_
COPY'
To restrict access to just creating and managing volume backups, including copying volume
backups between regions, use the policy in Let volume backup admins manage only backups.
If you are copying volume backups encrypted using Vault between regions or you want the
copied volume backup to use Vault for encryption in the destination region, you need to use a
policy that allows the Block Volume service to perform cryptographic operations with keys in
the destination region. For a sample policy showing this, see Let Block Volume, Object
Storage, File Storage, Container Engine for Kubernetes, and Streaming services encrypt and
decrypt volumes, volume backups, buckets, file systems, Kubernetes secrets, and stream
pools.
RESTRICTING ACCESS
The specific permissions needed to copy volume backups across regions are:
S AMPLE POLICIES
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
1. Open the navigation menu. Under Block Storage, click Block Volume Backups.
A list of the block volume backups in the compartment you're viewing is displayed. If
you don’t see the one you're looking for, make sure you’re viewing the correct
compartment (select from the list on the left side of the page).
2. Click the Actions icon (three dots) for the block volume backup you want to copy to
another region.
3. Click Copy to Another Region.
4. Enter a name for the backup and choose the region to copy the backup to.
5. In the Encryption section select whether you want the volume backup to use the
Oracle-provided encryption key or your own Vault encryption key. If you select the
option to use your own key, paste the OCID for encryption key from the destination
region.
6. Click Copy Block Volume Backup.
7. Confirm that the source and destination region details are correct in the confirmation
dialog and then click OK.
l CopyVolumeBackup
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.
Next Steps
After copying the block volume backup, switch to the destination region in the Console and
verify that the copied backup appears in the list of block volume backups for that region. You
can then restore the backup by creating a new block volume from it using the steps in
Restoring a Backup to a New Volume.
For more information about backups, see Overview of Block Volume Backups.
Cloning a Volume
You can create a clone from a volume using the Block Volume service. Cloning enables you to
make a copy of an existing block volume without needing to go through the backup and
restore process.
A cloned volume is a point-in-time direct disk-to-disk deep copy of the source volume, so all
the data that is in the source volume when the clone is created is copied to the clone volume.
Any subsequent changes to the data on the source volume are not copied to the clone. Since
the clone is a copy of the source volume it will be the same size as the source volume unless
you specify a larger volume size when you create the clone.
The clone operation occurs immediately, and you can attach and use the cloned volume as a
regular volume as soon as the state changes to available. At this point, the volume data is
being copied in the background, and can take up to thirty minutes depending on the size of the
volume.
There is a single point-in-time reference for a source volume while it is being cloned, so if the
source volume is attached when a clone is created, you need to wait for the first clone
operation to complete from the source volume before creating additional clones. If the source
volume is detached, you can create up to ten clones from the same source volume
simultaneously.
You can only create a clone for a volume within the same region, availability domain and
tenant. You can create a clone for a volume between compartments as long as you have the
required access permissions for the operation.
For more information about the Block Volume service and cloned volumes, see the Block
Volume FAQ.
Warning
Volume Supported. You can back up a Supported. You can clone a volume group.
groups volume group.
For more information about block volume backups, see Overview of Block Volume Backups
and Backing Up a Volume.
The volume is ready use when its icon lists it as AVAILABLE in the volume list. At this point,
you can perform various actions on the volume such as creating a clone from the volume,
attaching it to an instance, or deleting the volume.
To create a clone from a volume, use the CreateVolume operation and specify
VolumeSourceFromVolumeDetails for CreateVolumeDetails.
Warning
data.
3. You can now detach the volume without the risk of losing data.
Detaching a Volume
When an instance no longer needs access to a volume, you can detach the volume from the
instance without affecting the volume's data.
For administrators: The policy in Let users launch Compute instances includes the ability to
attach/detach existing block volumes. The policy in Let volume admins manage block
volumes, backups, and volume groups lets the specified group do everything with block
volumes and backups, but not launch instances.
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
Warning
1. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Instances.
2. In the Instance list locate the instance. Click its name to display the instance details.
3. In the Resources section on the Instance Details page, click Attached Block
Volumes
4. Click the Actions icon (three dots) next to the volume you want to detach, and then click
Detach. Confirm when prompted.
l DetachVolume
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.
Deleting a Volume
You can delete a volume that is no longer needed.
Warning
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: The policy in Let volume admins manage block volumes, backups, and
volume groups lets the specified group do everything with block volumes and backups.
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
l DeleteVolume
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.
immediately and affect access to the resource through the Console. For more information, see
Managing Compartments.
Important
Use the following operations for moving Block Volume resources between compartments:
l ChangeVolumeCompartment
l ChangeVolumeBackupCompartment
l ChangeVolumeGroupCompartment
l ChangeVolumeGroupBackupCompartment
l ChangeBootVolumeCompartment
l ChangeBootVolumeBackupCompartment
The Oracle Cloud Infrastructure Block Volume service lets you dynamically provision and
manage block storage volumes. You can create, attach, connect and move volumes as needed
to meet your storage and application requirements. The Block Volume service uses NVMe-
based storage infrastructure, and is designed for consistency. You just need to provision the
capacity needed and performance scales with the performance characteristics of the elastic
performance option selected up to the service maximums. See Block Volume Elastic
Performance for specific details about the elastic performance options.
The Block Volume service supports creating volumes sized from 50 GB to a maximum size of
32 TB, in 1 GB increments. You can attach up to 32 volumes to an instance, with a maximum
of 1 PB of attached volumes per instance. Latency performance is independent of the instance
shape or volume size, and is always sub-millisecond at the 95th percentile for the Balanced
and Higher Performance elastic performance options. Per instance performance is up to
700,000 IOPS, see Host Maximum.
Note
Higher Performance
The Higher Performance elastic performance option is recommended for workloads with
the highest I/O requirements, requiring the best possible performance, such as large
databases. This option provides the best linear performance scale with 75 IOPS/GB up to a
maximum of 35,000 IOPS per volume. Throughput also scales at the highest rate at 600
KBPS/GB up to a maximum of 480 MBPS per volume.
The following table lists the Block Volume service's throughput and IOPS performance
numbers based on volume size for this option. IOPS and KPBS performance scales linearly per
GB volume size up to the service maximums so you can predictably calculate the performance
numbers for a specific volume size. If you're trying to achieve certain performance targets for
volumes configured to use the Higher Performance elastic performance option you can
provision a minimum volume size using this table as a reference.
Balanced Performance
The Balanced elastic performance option provides a good balance between performance and
cost savings for most workloads, including those that perform random I/O such as boot
volumes. This option provides linear peformance scaling with 60 IOPS/GB up to 25,000 IOPS
per volume. Throughtput scales at 480 KBPS/GB up to a maximum of 480 MBPS per volume.
The following table lists the Block Volume service's throughput and IOPS performance
numbers based on volume size for this option. IOPS and KPBS performance scales linearly per
GB volume size up to the service maximums so you can predictably calculate the performance
numbers for a specific volume size. If you're trying to achieve certain performance targets for
volumes configured to use the Balanced elastic performance option you can provision a
minimum volume size using this table as a reference.
Lower Cost
The Lower Cost elastic performance option is recommended for throughput intensive
workloads with large sequential I/O, such as streaming, log processing, and data warehouses.
This option gives you linear scaling 2 IOPS/GB upt to a maximum of 3000 IOPS per volume.
The following table lists the Block Volume service's throughput and IOPS performance
numbers based on volume size for this option. IOPS and KPBS performance scales linearly per
GB volume size up to the service maximums so you can predictably calculate the performance
numbers for a specific volume size. If you're trying to achieve certain performance targets for
volumes configured to use the Lower Cost elastic performance option you can provision a
minimum volume size using this table as a reference.
For more information about FIO command samples you can use for performance testing see
Sample FIO Commands for Block Volume Performance Tests on Linux-based Instances.
Warning
This section describes the setup of the test environments, the methodology, and the observed
performance for the Balanced elastic performance configuration option. Some of the sample
volume sizes tested were:
These tests used a wide range of volume sizes and the most common read and write patterns
and were generated with the Gartner Cloud Harmony test suite. To show the throughput
performance limits, 256k or larger block sizes should be used. For most environments, 4K,
8K, or 16K blocks are common depending on the application workload, and these are used
specifically for IOPS measurements.
In the observed performance images in this section, the X axis represents the volume size
tested, ranging from 4KB to 1MB. The Y axis represents the IOPS delivered. The Z axis
represents the read/write mix tested, ranging from 100% read to 100% write.
Note
1 TB Block Volume
A 1 TB volume was mounted to a bare metal instance running in the Phoenix region. The
instance shape was dense, workload was direct I/O with 10GB working set. The following
command was run for the Gartner Cloud Harmony test suite:
~/block-storage/run.sh --nopurge --noprecondition --fio_direct\=1 --fio_size=10g --target /dev/sdb --
test iops --skip_blocksize 512b
The results showed that for 1 TB, the bandwidth limit for the larger block size test occurs at
320MBS.
50 GB Block Volume
A 50 GB volume was mounted to a bare metal instance running in the Phoenix region. The
instance shape was dense, workload was direct I/O with 10GB working set. The following
command was run for the Gartner Cloud Harmony test suite:
~/block-storage/run.sh --nopurge --noprecondition --fio_direct=1 --fio_size=10g --target /dev/sdb --test
iops --skip_blocksize 512b
The results showed that for the 50 GB volume, the bandwidth limit is confirmed as 24,000
KBPS for the larger block size tests (256 KB or larger block sizes), and the maximum of 3,000
IOPS at 4K block size is delivered. For small volumes, a 4K block size is common.
Host Maximum
Depending on the instance shape, a single instance with multiple attached volumes can
achieve performance of up to 700,000 IOPS when the elastic performance settings for the
attached volumes are set to balanced or higher performance.
To test performance, run the following command for the Gartner Cloud Harmony test suite
using thirty 800 GB higher performance volumes:
sudo ./run.sh --savefio --nopurge --noprecondition --nozerofill --nosecureerase --notrim -v --fio_
direct=1 --fio_size=10g --target
/dev/sdy,/dev/sdf,/dev/sdab,/dev/sdo,/dev/sdw,/dev/sdd,/dev/sdm,/dev/sdu,/dev/sdb,/dev/sdk,/dev/sds,/de
v/sdi,/dev/sdq,/dev/sdae,/dev/sdz,/dev/sdg,/dev/sdac,/dev/sdx,/dev/sde,/dev/sdaa,/dev/sdn,/dev/sdv,/dev
/sdc,/dev/sdl,/dev/sdt,/dev/sdj,/dev/sdr,/dev/sdh,/dev/sdp,/dev/sdad --test iops --skip_blocksize 512b&
Installing FIO
To install and configure FIO on your instances with Linux-based operating systems, run the
commands applicable to the operating system version for your instance.
This applies to Oracle Autonomous Linux 7.x, Oracle Linux 6.x, Oracle Linux 7.x, CentOS 6.x,
and CentOS 7.x.
Ubuntu
Run the following commands to install and configure FIO for your Ubuntu systems:
sudo apt-get update && sudo apt-get install fio -y
This applies to Ubuntu 16.04, 18.04, and Ubuntu Minimal 16.04, 18.04.
FIO Commands
Use the following FIO example commands to test IOPS performance. You can run the
commands directly or create a job file with the command and then run the job file.
In some cases you might see more consistent results if you use a job file instead of running
the command directly. Use the following steps for this approach.
[job1]
filename=device name
Add both the read IOPS and the write IOPS returned.
Warning
Add both the read IOPS and the write IOPS returned.
In some cases you might see more consistent results if you use a job file instead of running
the command directly. Use the following steps for this approach.
[job1]
filename=device name
In some cases you may see more consistent results if you use a job file instead of running the
command directly. Use the following instructions for this approach:
[job1]
filename=device name
In some cases you might see more consistent results if you use a job file instead of running
the command directly. Use the following steps for this approach.
[job1]
filename=device name
Add both the read MBPs and the write MBPs returned.
Warning
Add both the read MBPs and the write MBPs returned.
In some cases you might see more consistent results if you use a job file instead of running
the command directly. Use the following steps for this approach.
[job1]
filename=device name
In some cases you might see more consistent results if you use a job file instead of running
the command directly. Use the following steps for this approach.
[job1]
filename=device name
Use the following FIO example commands to test latency performance. You can run the
commands directly or create a job file with the command and then run the job file.
In some cases you might see more consistent results if you use a job file instead of running
the command directly. Use the following steps for this approach.
[job1]
filename=device name
Warning
that is in use.
Run the following command directly to test random read/writes for latency:
sudo fio --filename=device name --direct=1 --rw=randrw --bs=4k --ioengine=libaio --iodepth=1 --numjobs=1
--time_based --group_reporting --name=rwlatency-test-job --runtime=120 --eta-newline=1 --readonly
In some cases you might see more consistent results if you use a job file instead of running
the command directly. Use the following steps for this approach.
[job1]
filename=device name
This feature includes the concept of volume performance units (VPUs). You can purchase
more VPUs to allocate more resources to a volume, increasing IOPS/GB and throughput per
GB. You also have the flexibility to purchase fewer VPUs, which reduces the performance
characteristics for a volume, however it can also provide cost savings. You can also choose
not to purchase any VPUs which can provide significant cost savings for volumes that don't
require the increased performance characteristics.
l Balanced: This is the default setting for new and existing block and boot volumes. It
provides a good balance between performance and cost savings for most workloads,
including those that perform random I/O such as boot volumes. This option provides
linear peformance scaling with 60 IOPS/GB up to 25,000 IOPS per volume. Throughtput
scales at 480 KBPS/GB up to a maximum of 480 MBPS per volume. With this option you
are purchasing 10 VPUs per GB/month.
l Higher Performance: Recommended for workloads with the highest I/O
requirements, requiring the best possible performance, such as large databases. This
option provides the best linear performance scale with 75 IOPS/GB up to a maximum of
35,000 IOPS per volume. Throughput also scales at the highest rate at 600 KBPS/GB up
to a maximum of 480 MBPS per volume. With this option you are purchasing 20 VPUs
per GB/month.
l Lower Cost: Recommended for throughput intensive workloads with large sequential
I/O, such as streaming, log processing, and data warehouses. The cost is only the
storage cost, there is no additional VPU cost. This option gives you linear scaling 2
IOPS/GB upt to a maximum of 3000 IOPS per volume. This option is only available for
block volumes, it is not available for boot volumes.
The following table lists the performance characteristics for each elastic performance level.
See Block Volume Performance for additional performance details for the Block Volume
service.
VPUs refer to volume performance units, see Oracle Storage Cloud Pricing for specific pricing
details.
You can configure the volume performance for a block volume when you create a volume, see
Creating a Volume. You can also change the volume performance for an existing block
volume, see To change the volume performance for an existing block volume.
When you create a Compute instance, the volume performance for the instance's boot volume
is set to Balanced by default. You can change this setting after the instance has launched,
see To change the volume performance for an existing boot volume.
The Block Volume service's elastic performance feature enables you to dynamically configure
the volume performance for block volumes and boot volumes, for more information, see
Block Volume Elastic Performance.
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: The policy in Let volume admins manage block volumes, backups, and
volume groups lets the specified group do everything with block volumes and backups, but not
launch instances.
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
LIMITATIONS
l You can only change the elastic performance configuration on three volumes
concurrently per tenancy.
l When changing volume performance for boot volumes, you can only select the
Balanced or Higher Performance options.
The default volume performance setting for existing block volumes or when you create a new
block volume is Balanced. You can change the default setting when you create a new block
volume, see Creating a Volume. You can also change the volume performance setting for an
existing block volume using the steps in the following procedure.
When you create an instance, the volume performance setting for the instance's boot volume
is set to Balanced. You can change this setting to Higher Performance after the instance
has been launched.
For information about using the CLI, see Command Line Interface (CLI).
Use the volume update operation or the boot-volume update operation with vpus-per-gb
parameter to update a block volume's elastic performance setting. The vpus-per-gb
parameter is where you specify the volume performance units (VPUs). VPUs represent the
volume performance settings, with the following allowed values:
For example:
oci bv volume update --volume-id <volume_ID> --vpus-per-gb 20
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.
BLOCK VOLUMES
l UpdateVolume
BOOT VOLUMES
l UpdateBootVolume
This topic describes the metrics emitted by the metric namespace oci_blockstore (the Block
Volume service)
See Using Block Volumes Service Metrics to Calculate Block Volume Throughput and IOPS for
a walkthrough of a performance testing scenario with FIO that shows how you can use these
metrics to determine the performance characteristics of your block volume.
The metrics listed in the following table are automatically available for any block volume or
boot volume, regardless of whether the attached instance has monitoring enabled. You do not
need to enable monitoring on the volumes to get these metrics.
You also can use the Monitoring service to create custom queries.
ATTACHMENTID
RESOURCEID
3. Under Resources, click either Attached Block Volumes or Boot Volume to view the
volume you're interested in.
4. Click the volume to view its details.
5. Under Resources, click Metrics.
For more information about monitoring metrics and using alarms, see Monitoring Overview.
For information about notifications for alarms, see Notifications Overview.
For more information about monitoring metrics and using alarms, see Monitoring Overview.
For information about notifications for alarms, see Notifications Overview.
Note
l Attestation. A Payment Card Industry (PCI) Data Security Standard (DSS) Attestation
of Compliance document.
l Audit. A general audit report.
l Bridge Letter (BridgeLetter). A bridge letter. Bridge letters provide compliance
information for the period of time between the end date of an SOC report and the date
of the release of a new SOC report.
l Certificate. A document indicating certification by a particular authority, with regard to
certification requirements and examination results conforming to said requirements.
l SOC3. A Service Organization Controls 3 audit report that provides information relating
to a service organization's internal controls for security, availability, confidentiality, and
privacy.
l Other. A compliance document that doesn't fit into any of the preceding, more specific
categories.
If you need to further narrow down what documents are displayed, you can combine the type
filter with the environment filter.
Types of Environments
The environments, or business pillars or platforms, to which the documents belong include:
To access the Console, you must use a supported browser. Oracle Cloud Infrastructure
supports the following browsers and versions:Google Chrome 69 or laterSafari 12.1 or
laterFirefox 62 or later
2. By default, the list displays documents according to the document name, in alphabetical
order. To sort the list another way, do one of the following:
l Click Name. The list sorts alphabetically, according to the summary of the
announcement. If you begin by viewing the default sort order, the sort order will
change to show documents in reverse alphabetical order by name.
l Click Type. The list sorts according to the type of the document, in alphabetical
order by type.
l Click Created. The list sorts according to the date and time the document was
created.
3. To sort the list again, repeat the previous step.
Oracle Cloud Infrastructure offers both bare metal and virtual machine instances:
l Bare Metal: A bare metal compute instance gives you dedicated physical server access
for highest performance and strong isolation.
l Virtual Machine: A virtual machine (VM) is an independent computing environment
that runs on top of physical bare metal hardware. The virtualization makes it possible to
run multiple VMs that are isolated from each other. VMs are ideal for running
applications that do not require the performance and resources (CPU, memory, network
bandwidth, storage) of an entire physical machine.
An Oracle Cloud Infrastructure VM compute instance runs on the same hardware as a
bare metal instance, leveraging the same cloud-optimized hardware, firmware,
software stack, and networking infrastructure.
Be sure to review Best Practices for Your Compute Instance for important information about
working with your Oracle Cloud Infrastructure Compute instance.
Oracle Cloud Infrastructure uses Oracle Ksplice to apply important security and other critical
kernel updates to the hypervisor hosts without a reboot. Oracle Cloud Infrastructure can apply
these patches transparently without the need to pause any VMs, and all hypervisor hosts
support this capability. For more information, see Installing and Running Oracle Ksplice.
Compute is Always Free eligible. For more information about Always Free resources,
including additional capabilities and limitations, see Oracle Cloud Infrastructure Free Tier.
Instance Types
When you create a Compute instance, you can select the most appropriate type of instance for
your applications based on characteristics such as the number of CPUs, amount of memory,
and network resources. Oracle Cloud Infrastructure offers a variety of shapes that are
designed to meet a range of compute and application requirements:
l Standard shapes: Designed for general purpose workloads and suitable for a wide
range of applications and use cases. Standard shapes provide a balance of cores,
memory, and network resources. Standard shapes are available with Intel or AMD
processors.
l DenseIO shapes: Designed for large databases, big data workloads, and applications
that require high-performance local storage. DenseIO shapes include locally-attached
NVMe-based SSDs.
l GPU shapes: Designed for hardware-accelerated workloads. GPU shapes include Intel
CPUs and NVIDIA graphics processors.
l High performance computing (HPC) shapes: Designed for high-performance
computing workloads that require high frequency processor cores and cluster
networking for massively parallel HPC workloads. HPC shapes are available for bare
metal instances only.
Flexible shapes let you customize the number of OCPUs that are allocated to an instance. The
amount of memory, network bandwidth, and number of VNICs scale proportionately with the
number of OCPUs. For more information, see Flexible Shapes.
For more information about the available bare metal and VM shapes, see Compute Shapes,
Bare Metal Instances, Virtual Machines, and Virtual Machines and Bare Metal (GPU).
AVAILABILITY DOMAIN
The Oracle Cloud Infrastructure data center within your geographical region that hosts
cloud resources, including your instances. You can place instances in the same or different
availability domains, depending on your performance and redundancy requirements. For
more information, see Regions and Availability Domains.
TAGS
You can apply tags to your resources to help you organize them according to your
business needs. You can apply tags at the time you create a resource, or you can update
the resource later with the desired tags. For general information about applying tags, see
Resource Tags.
IMAGE
A template of a virtual hard drive that determines the operating system and other
software for an instance. For details about Oracle Cloud Infrastructure platform images,
see Oracle-Provided Images. You can also launch instances from:
l Trusted third-party images published by Oracle partners from the Partner Image
catalog. For more information about partner images, see Overview of Marketplace
and Working with Listings.
l Pre-built Oracle enterprise images and solutions enabled for Oracle Cloud
Infrastructure
l Custom images, including bring your own image scenarios.
l Boot Volumes.
SHAPE
A template that determines the number of CPUs, amount of memory, and other resources
allocated to a newly created instance. You choose the most appropriate shape when you
launch an instance. See Compute Shapes for a list of available bare metal and VM shapes.
You can optionally attach volumes to an instance. For more information, see Overview of
Block Volume.
Resource Identifiers
Most types of Oracle Cloud Infrastructure resources have a unique, Oracle-assigned identifier
called an Oracle Cloud ID (OCID). For information about the OCID format and other ways to
identify your resources, see Resource Identifiers.
Work Requests
Compute is one of the Oracle Cloud Infrastructure services that is integrated with the Work
Requests API. For general information on using work requests in Oracle Cloud Infrastructure,
see Work Requests in the user guide, and the Work Requests API.
For general information about using the API, see REST APIs.
An administrator in your organization needs to set up groups, compartments, and policies that
control which users can access which services, which resources, and the type of access. For
example, the policies control who can create new users, create and manage the cloud
network, launch instances, create buckets, download objects, etc. For more information, see
Getting Started with Policies. For specific details about writing policies for each of the
different services, see Policy Reference.
If you’re a regular user (not an administrator) who needs to use the Oracle Cloud
Infrastructure resources that your company owns, contact your administrator to set up a user
ID for you. The administrator can confirm which compartment or compartments you should be
using.
l Block Volume: Lets you dynamically provision and manage block volumes that you
can attach to one or more Compute instances. See Overview of Block Volume for more
information. For steps to attach block volumes to Compute instances, see Attaching a
Volume and Attaching a Volume to Multiple Instances.
l File Storage: A durable, scalable, secure, enterprise-grade network file system that
you can connect to from any Compute instance in your virtual cloud network (VCN). See
Overview of File Storage for more information.
l Object Storage: An internet-scale, high-performance storage platform that lets you
store an unlimited amount of unstructured data of any content type. This storage is
regional and not tied to any specific Compute instance. See Overview of Object Storage
for more information.
l Archive Storage: A storage platform that lets you store an unlimited amount of
unstructured data of any content type that doesn't require instantaneous data retrieval.
This storage is regional and not tied to any specific Compute instance. See Overview of
Archive Storage for more information.
l To attach a volume to an instance, both the instance and volume must be within the
same availability domain.
l Many Compute operations are subject to throttling.
Custom metadata keys (any key you define that is not ssh_authorized_keys or user_data)
have the following limits:
ssh_authorized_keys is a special key that does not have these limits, but its value is
validated to conform to a public key in the OpenSSH format.
user_data has a maximum size of 16KB. For Linux instances with cloud-init configured, you
can populate the user_data field with a Base64-encoded string of cloud-init user data. For
more information on formats that cloud-init accepts, see cloud-init formats.
by Oracle’s next generation, internet-scale infrastructure, designed to help you develop and
run your most demanding applications and workloads in the cloud.
You can provision compute capacity through an easy-to-use web console or the API, SDKs, or
CLI. The compute instance, once provisioned, provides you with access to the host. This gives
you complete control of your instance.
Though you have full management authority for your instance, we recommend a variety of
best practices to ensure system availability and top performance.
169.254.0.0/16
These addresses are used for iSCSI connections to the boot and block volumes, instance
metadata, and other services.
All addresses from 224.0.0.0 to 239.255.255.255 (Class D) are prohibited for use in a VCN,
they are reserved for multicast address assignments in the IP standards. See RFC 3171 for
details.
All addresses from 240.0.0.0 to 255.255.255.255 (Class E) are prohibited for use in a VCN,
they are reserved for future use in the IP standards. See RFC 1112, Section 4 for details.
For example, in a subnet with CIDR 192.168.0.0/24, these addresses are reserved:
The remaining addresses in the CIDR (192.168.0.2 to 192.168.0.254) are available for use.
l We recommend that you do not reconfigure the firewall on your instance to remove
these rules. Removing these rules allows non-root users or non-administrators to
access the instance’s boot disk volume.
l We recommend that you do not create custom images without these rules unless you
understand the security risks.
l Running Uncomplicated Firewall (UFW) on Ubuntu images might cause issues with these
rules. Because of this, we recommend that you do not enable UFW on your instances.
See Ubuntu Instance fails to reboot after enabling Uncomplicated Firewall (UFW) for
more information.
System Resilience
Follow industry-wide hardware failure best practices to ensure the resilience of your solution
in the event of a hardware failure. Some best practices include:
l Design your system with redundant compute nodes in different availability domains to
support failover capability.
l Create a custom image of your system drive each time you change the image.
l Back up your data drives, or sync to spare drives, regularly.
If you experience a hardware failure and have followed these practices, you can terminate the
failed instance, launch your custom image to create a new instance, and then apply the
backup data.
Stopping the DHCP client might remove the host route table when the lease expires. Also, loss
of network connectivity to your iSCSI connections might result in loss of the boot drive.
User Access
If you created your instance using an Oracle-provided Linux image, you can use SSH to access
your instance from a remote host as the opc user. After logging in, you can add users on your
instance.
If you do not want to share SSH keys, you can create additional SSH-enabled users.
If you created your instance using an Oracle-provided Windows image, you can access your
instance using a Remote Desktop client as the opc user. After logging in, you can add users on
your instance.
For more information about user access, see Adding Users on an Instance. For steps to log in
to an instance, see Connecting to an Instance.
NTP Service
Oracle Cloud Infrastructure offers a fully managed, secure, and highly available NTP service
that you can use to set the date and time of your Compute and Database instances from within
your virtual cloud network (VCN). We recommend that you configure your instances to use the
Oracle Cloud Infrastructure NTP service. For information about how to configure instances to
use this service, see Configuring the Oracle Cloud Infrastructure NTP Service for an Instance.
Fault Domains
A fault domain is a grouping of hardware and infrastructure that is distinct from other fault
domains in the same availability domain. Each availability domain has three fault domains. By
properly leveraging fault domains you can increase the availability of applications running on
Oracle Cloud Infrastructure. See Fault Domains for more information.
Your application's architecture will determine whether you should separate or group instances
using fault domains.
In this scenario you have a highly available application, for example you have two web
servers and a clustered database. In this scenario you should group one web server and one
database node in one fault domain and the other half of each pair in another fault domain. This
ensures that a failure of any one fault domain does not result in an outage for your
application.
In this scenario your application architecture is not highly available, for example you have
one web server and one database instance. In this scenario both the web server and the
database instance must be placed in the same fault domain. This ensures that your application
will only be impacted by the failure of that single fault domain.
A maintenance reboot is different from a normal reboot. When you reboot an instance for
maintenance, the instance is stopped on the physical VM host that needs maintenance, and
then restarted on a healthy VM host.
If you choose not to reboot before the scheduled time, then Oracle Cloud Infrastructure will
reboot and migrate your instances before proceeding with the planned infrastructure
maintenance. For more information, see Rebooting a Virtual Machine (VM) During Planned
Maintenance.
This topic describes how to configure your Compute instances to use this NTP service.
You can also choose to configure your instances to use a public NTP service or use
FastConnect to leverage an on-premises NTP service.
1. Configure IPtables to allow connections to the Oracle Cloud Infrastructure NTP service,
using the following commands:
sudo iptables -I BareMetalInstanceServices 8 -d 169.254.169.254/32 -p udp -m udp --dport 123 -m
comment --comment "Allow access to OCI local NTP service" -j ACCEPT
4. Configure the instance to use the Oracle Cloud Infrastructure NTP service for iburst. To
configure, modify the /etc/ntp.conf file as follows:
a. In the server section, comment out the lines specifying the RHEL servers:
#server 0.rhel.pool.ntp.org iburst
#server 1.rhel.pool.ntp.org iburst
#server 2.rhel.pool.ntp.org iburst
#server 3.rhel.pool.ntp.org iburst
5. Set the NTP service to launch automatically when the instance boots with the following
command:
sudo chkconfig ntpd on
7. Confirm that the NTP service is configured correctly with the following command:
ntpq -p
Note
Use the following steps to configure your Oracle Linux 7.x instances to use the Oracle Cloud
Infrastructure NTP service.
3. Change the firewall rules to allow inbound and outbound traffic with the Oracle Cloud
Infrastructure NTP server, at 169.254.169.254, on UDP port 123 with the following
command:
awk -v n=13 -v s=' <passthrough ipv="ipv4">-A OUTPUT -d 169.254.169.254/32 -p udp -m udp --dport
123 -m comment --comment "Allow access to OCI local NTP service" -j ACCEPT </passthrough>' 'NR ==
n {print s} {print}' /etc/firewalld/direct.xml > tmp && mv tmp /etc/firewalld/direct.xml
At the prompt:
mv: overwrite ‘/etc/firewalld/direct.xml’?
enter y
4. Restart the firewall with the following command:
service firewalld restart
6. Configure the instance to use the Oracle Cloud Infrastructure NTP service for iburst. To
configure, modify the /etc/ntp.conf file as follows:
a. In the server section comment out the lines specifying the RHEL servers:
#server 0.rhel.pool.ntp.org iburst
#server 1.rhel.pool.ntp.org iburst
#server 2.rhel.pool.ntp.org iburst
#server 3.rhel.pool.ntp.org iburst
7. Start and enable the NTP service with the following commands:
systemctl start ntpd
systemctl enable ntpd
You also need disable the chrony NTP client to ensure that the NTP service starts
automatically after a reboot, using the following commands:
systemctl stop chronyd
systemctl disable chronyd
8. Confirm that the NTP service is configured correctly with the following command:
ntpq -p
Steps 1 - 7 below walk you though these registry changes, you can use these steps to
manually edit the registry instead of using PowerShell. If you use the PowerShell commands,
you can skip steps 1 - 7, and proceed with steps 8 and 9 to complete the process of
configuring your Windows instance to use the Oracle Cloud Infrastructure NTP service.
b. Click Type.
c. Change the value to NTP and click OK.
2. Configure the Windows Time service to enable the Timeserv_Announce_Yes and
Reliable_Timeserv_Announce_Auto flags.
To configure, set the AnnounceFlags parameter to 5:
a. From Registry Editor, navigate to:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W32Time\Config\
b. Click AnnounceFlags.
c. Change the value to 5 and click OK.
3. Enable the NTP server:
a. From Registry Editor, navigate to:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W32Time\TimeProviders\NtpServer\
b. Click Enabled.
c. Change the value to 1 and click OK.
4. Set the time sources:
a. From Registry Editor, navigate to:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W32Time\Parameters\
b. Click NtpServer.
c. Change the value to 169.254.169.254,0x9 and click OK.
5. Set the poll interval:
b. Click SpecialPollInterval.
c. Set the value to the interval that you want the time service to synchronize on. The
value is in seconds. To set it for 15 minutes, set the value to 900, and click OK.
6. Set the phase correction limit settings to restrict the time sample boundaries:
a. From Registry Editor, navigate to:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W32Time\Config\
b. Click MaxPosPhaseCorrection.
c. Set the value to the maximum time offset in the future for time samples. The
value is in seconds. To set it for 30 minutes, set the value to 1800 and click OK.
d. Click MaxNegPhaseCorrection.
e. Set the value to the maximum time offset in the past for time samples. The value
is in seconds. To set it for 30 minutes, set the value to 1800 and click OK.
7. Restart the time service by running the following command from a command prompt:
net stop w32time && net start w32time
8. Test the connection to the NTP service by running the following command from a
command prompt:
w32tm /query /peers
Peer: 169.254.169.254,0x9
State: Active
Time Remaining: 22.1901786s
Mode: 3 (Client)
Stratum: 0 (unspecified)
PeerPoll Interval: 10 (1024s)
HostPoll Interval: 10 (1024s)
After the time specified in the poll interval has elapsed, State will change from Pending
to Active.
Note that these devices are not protected in any way; they are individual devices locally
installed on your instance. Oracle Cloud Infrastructure does not take images, back up, or use
RAID or any other methods to protect the data on NVMe devices. It is your responsibility to
protect and manage the durability the data on these devices.
Oracle Cloud Infrastructure offers high-performance remote block (iSCSI) LUNs that are
redundant and can be backed up using an API call. See Overview of Block Volume for more
information.
See Compute Shapes for information about which shapes support local NVMe storage.
A protected RAID array is the most recommended way to protect against an NVMe device
failure. There are three RAID levels that can be used for the majority of workloads:
l RAID 1: An exact copy (or mirror) of a set of data on two or more disks; a classic
RAID 1 mirrored pair contains two disks, as shown:
l RAID 10: Stripes data across multiple mirrored pairs. As long as one disk in each
mirrored pair is functional, data can be retrieved, as shown:
l RAID 6: Block-level striping with two parity blocks distributed across all member disks,
as shown.
For more information about RAID and RAID levels, see RAID.
Because the appropriate RAID level is a function of the number of available drives, the
number of individual LUNs needed, the amount of space needed, and the performance
requirements, there isn't one correct choice. You must understand your workload and design
accordingly.
There are several options for BM.DenseIO1.36 instances with nine NVMe devices:
Create a single RAID 6 device across all nine devices. This array is redundant, performs well,
will survive the failure of any two devices, and will be exposed as a single LUN with about
23.8TB of usable space.
Use the following commands to create a single RAID 6 device across all nine devices:
$ sudo yum install mdadm -y
Create a four device RAID 10 and a five device RAID 6 array. These arrays would be exposed
as two different LUNs to your applications. This is a recommended choice when you need to
isolate one type of I/O from another, such as log and data files. In this example, your RAID 10
array would have about 6.4TB of usable space and the RAID 6 array would have about 9.6TB
of usable space.
Use the following commands to create a four-device RAID 10 and a five-device RAID 6 array:
$ sudo yum install mdadm -y
If you need the best possible performance and can sacrifice some of your available space,
then an eight-device RAID 10 array is an option. Because RAID 10 requires an even number of
devices, the ninth device is left out of the array and serves as a hot spare in case another
device fails. This creates a single LUN with about 12.8 TB of usable space.
The following command adds /dev/nvme8n as a hot spare for the /dev/md0 array:
$ sudo mdadm /dev/md0 --add /dev/nvme8n1
For the best possible performance and I/O isolation across LUNs, create two four-device RAID
10 arrays. Because RAID 10 requires an even number of devices, the ninth device is left out of
the arrays and serves as a global hot spare in case another device in either array fails. This
creates two LUNS, each with about 6.4 TB of usable space.
Use the following commands to create two four-device RAID 10 arrays with a global hot
spare:
$ sudo yum install mdadm -y
1. Add the spare to either array (it does not matter which one) by running these
commands:
$ sudo mdadm /dev/md0 --add /dev/nvme8n1
2. Edit /etc/mdadm to put both arrays in the same spare-group. Add spare-group=global
to the end of the line that starts with ARRAY, as follows:
$ sudo vi /etc/mdadm.conf
It's important for you to be notified if a device in one of your arrays fails. Mdadm has built-in
tools that can be utilized for monitoring, and there are two options you can use:
l Set the MAILADDR option in /etc/mdadm.conf and then run the mdadm monitor as a
daemon
l Run an external script when mdadm detects a failure
S ET THE MAILADDR OPTION IN /ETC/MDADM.CONF AND RUN THE MDADM MONITOR AS A DAEMON
The simplest method is to set the MAILADDR option in /etc/mdadm.conf, and then run the
mdadm monitor as a daemon, as follows:
1. The DEVICE partitions line is required for MAILADDR to work; if it is missing, you must
add it, as follows:
$ sudo vi /etc/mdadm.conf
DEVICE partitions
MAILADDR <[email protected]>
3. To verify that the monitor runs at startup, run the following commands:
$ sudo chmod +x /etc/rc.d/rc.local
$ sudo vi /etc/rc.local
4. To verify that the email and monitor are both working run the following command:
$ sudo mdadm --monitor --scan --test -1
Note that these emails will likely be marked as spam. The PROGRAM option, described
later in this topic, allows for more sophisticated alerting and messaging.
A more advanced option is to create an external script that would run if the mdadm monitor
detects a failure. You would integrate this type of script with your existing monitoring
solution. The following is an example of this type of script:
$ sudo vi /etc/mdadm.events
#!/bin/bash
event=$1
device=$2
if [ $event == "Fail" ]
then
<"do something">
else
if [ $event == "FailSpare" ]
then
<"do something else">
else
if [ $event == "DegradedArray" ]
then
<"do something else else">
else
if [ $event == "TestMessage" ]
then
<"do something else else else">
fi
fi
fi
fi
Next, add the PROGRAM option to /etc/mdadm.conf, as shown in the following example:
1. The DEVICE partitions line is required for MAILADDR to work; if it is missing, you must
add it, as follows:
$ sudo vi /etc/mdadm.conf
DEVICE partitions
MAILADDR <[email protected]>
PROGRAM /etc/mdadm.events
3. To verify that the monitor runs at startup, run the following commands:
$ sudo chmod +x /etc/rc.d/rc.local
$ sudo vi /etc/rc.local
4. To verify that the email and monitor are both working run the following command:
$ sudo mdadm --monitor --scan --test -1
Note that these emails will likely be marked as spam. The PROGRAM option, described
later in this topic, allows for more sophisticated alerting and messaging.
You can use mdadm to manually cause a failure of a device to see whether your RAID array can
survive the failure, as well as test the alerts you have set up.
2. Recover the device or your array might not be protected. Use the following command:
$ sudo mdadm /dev/md0 --add /dev/nvme0n1
Your array will automatically rebuild in order to use the "new" device. Performance will
be decreased during this process.
3. You can monitor the rebuild status by running the following command:
$ sudo mdadm --detail /dev/md0
Compute resources in the cloud are designed to be temporary and fungible. If an NVMe device
fails while the instance is in service, you should start another instance with the same amount
of storage or more, and then copy the data onto the new instance, replacing the old instance.
There are multiple toolsets for copying large amounts of data, with rsync being the most
popular. Since the connectivity between instances is a full 10 Gb/sec, copying data should be
quick. Remember that with a failed device, your array may no longer be protected, so you
should copy the data off of the impacted instance as quickly as possible.
The Linux Logical Volume Manager (LVM) provides a rich set of features for managing
volumes. If you need these features, we strongly recommend that you use mdadm as described
in preceding sections of this topic to create the RAID arrays, and then use LVM's pvcreate,
vgcreate, and lvcreate commands to create volumes on the mdadm LUNs. You should not use
LVM directly against your NVMe devices.
Once your data is protected against the loss of a NVMe device, you need to protect it against
the loss of an instance or the loss of the availability domain. This type of protection is typically
done by replicating your data to another availability domain or backing up your data to
another location. The method you choose depends on your objectives. For details, see the
disaster recovery concepts of Recovery Time Objective (RTO) and Recovery Point Objective
(RPO).
REPLICATION
Replicating your data from one instance in one availability domain to another has the lowest
RTO and RPO at a significantly higher cost than backups; for every instance in one availability
domain, you must have another instance in a different availability domain.
For Oracle database workloads, you should use the built-in Oracle Data Guard functionality to
replicate your databases. Oracle Cloud Infrastructure availability domains are each close
enough to each other to support high performance, synchronous replication. Asynchronous
replication is also an option.
For general-purpose block replication, DRBD is the recommended option. You can configure
DRBD to replicate, synchronously or asynchronously, every write in one availability domain to
another availability domain.
BACKUPS
Traditional backups are another way to protect data. All commercial backup products are fully
supported on Oracle Cloud Infrastructure. If you use backups, the RTO and RPO are
significantly higher than using replication because you must recreate the compute resources
that failed and then restore the most recent backup. Costs are significantly lower because you
don't need to maintain a second instance. Do not store your backups in the same availability
domain as their original instance.
The two recommended ways of protecting against data corruption or loss from application or
user error are regularly taking snapshots or creating backups.
S NAPSHOTS
The two easiest ways to maintain snapshots are to either use a file system that supports
snapshots, such as ZFS, or use LVM to create and manage the snapshots. Because of the way
LVM has implemented copy-on-write (COW), performance may significantly decrease when a
snapshot is taken using LVM.
BACKUPS
All commercial backup products are fully supported on Oracle Cloud Infrastructure. Make sure
that your backups are stored in a different availability domain from the original instance.
Boot Volumes
When you launch a virtual machine (VM) or bare metal instance based on an Oracle-provided
image or custom image, a new boot volume for the instance is created in the same
compartment. That boot volume is associated with that instance until you terminate the
instance. When you terminate the instance, you can preserve the boot volume and its data.
For more information, see Terminating an Instance. This feature gives you more control and
management options for your compute instance boot volumes, and enables:
l Instance scaling: When you terminate your instance, you can keep the associated
boot volume and use it to launch a new instance using a different instance type or
shape. See Creating an Instance for steps to launch an instance based on a boot
volume. This allows you to switch easily from a bare metal instance to a VM instance
and vice versa, or scale up or down the number of cores for an instance.
l Troubleshooting and repair: If you think a boot volume issue is causing a compute
instance problem, you can stop the instance and detach the boot volume. Then you can
attach it to another instance as a data volume to troubleshoot it. After resolving the
issue, you can then reattach it to the original instance or use it to launch a new instance.
Boot volumes are encrypted by default, the same as other block storage volumes. For more
information, see Block Volume Encryption.
Important
You can group boot volumes with block volumes into the same volume group, making it easy
to create a group volume backup or a clone of your entire instance, including both the system
disk and storage disks at the same time. See Volume Groups for more information.
You can move Block Volume resources such as boot volumes and boot volume backups
between compartments. For more information, see Move Block Volume Resources Between
Compartments.
For more information about the Block Volume service and boot volumes, see the Block
Volume FAQ.
l Oracle-provided image
l Custom image
l Image OCID
For Linux-based images, the custom boot volume size must be larger than the image's default
boot volume size or 50 GB, whichever is higher.
For Windows-based images, the custom boot volume size must be larger than the image's
default boot volume size or 256 GB, whichever is higher. The minimum size requirement for
Windows images is to ensure that there is enough space available for Windows patches and
updates that can require a large amount of space, to improve performance, and to provide
adequate space for setting a suitable page file (see this Microsoft known issue for page file
settings on Windows Server 2012 R2).
After you launch an instance, you can't change the boot volume size.
If you specify a custom boot volume size, you need to extend the volume to take advantage of
the larger size. For steps, see Extending the Partition for a Boot Volume.
The Block Volume service's elastic performance feature enables you to dynamically change
the volume performance for boot volumes. Once an instance has been created, you can
change the volume performance of the boot volume to one of the following performance
options:
l Balanced
l Higher Performance
For more information about this feature and the performance options, see Block Volume
Elastic Performance and Changing the Performance of a Volume
For administrators: The policy in Let users launch Compute instances includes the ability to
list boot volumes. The policy in Let volume admins manage block volumes, backups, and
volume groups lets the specified group do everything with block volumes, boot volumes, and
backups, but not launch instances.
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
l BootVolume
l ListBootVolumes
l GetBootVolume
l UpdateBootVolume
l DetachBootVolume
l DeleteVolume
l BootVolumeAttachment
l AttachBootVolume
l GetBootVolumeAttachment
l ListBootVolumeAttachments
Note
Extending a partition on an instance does not require a specific IAM policy. However, you may
need permission to run the necessary commands on the instance's guest OS. Contact your
system administrator for more information.
For instances running Linux-based images, you need to extend the root partition and then
grow the file system.
2. When you run parted, you may encounter the following error message:
Warning: Not all of the space available to <volume_id> appears to be used,
you can fix the GPT to use all of the space (an extra volume_size blocks)
or continue with the current setting?
You are then prompted to fix the error or ignore the error and continue with the current
setting. Specify the option to fix the error.
3. Run the following command to change the display units to sectors so that you can see
the precise start position for the volume:
(parted) unit s
4. Run the following command to display the current partitions in the partition table:
(parted) print
Make note of the values in the Number, Start, and File system columns for the root
partition.
5. Run the following command to remove the existing root partition:
(parted) rm <partition_number>
At the Start? prompt, specify the value from the Start column. At the File system
type? prompt, specify the value from the File system column. Specify 100% for the
End? prompt.
7. Run the following command to exit parted:
(parted) quit
This command forces a rewrite of the partition table with the new partition settings that
you specified.
8. To verify that the root partition was extended, run the following command to list the
attached block volumes:
lsblk
After you extend the root partition, you need to grow the file system. The steps in the
following procedure apply only to xfs file systems.
<partition_id> is the partition identifier, for example /dev/sdc3. See Checking and
Repairing an XFS File System for more information.
2. After you have confirmed that there are no more issues to repair, you need to create a
mount point to run the xfs_growfs against. To do this, create a directory and mount the
partition to that directory by running the following commands:
mkdir <directory_name>
mount <partition_id> <directory_name> -o nouuid
<directory_name> is the name for the directory you created in the previous step.
4. To verify that the file system size is correct, run the following command to display the
file system details:
df -lh
5. Once you have verified that the file system size is correct, run the following command
to unmount the partition:
umount <partition_id>
On Windows-based images, you can extend a partition using the Windows interface or from
the command line using the DISKPART utility.
The steps for extending a system partition on instances running Windows Server 2012,
Windows Server 2016, or Windows Server 2019 are the same, and are described in the
following procedures.
Extending the system partition using the command line with DISKPART
1. Open a command prompt as administrator on the instance.
2. Run the following command to start the DISKPART utility:
diskpart
3. At the DISKPART prompt, run the following command to display the instance's volumes:
list volume
<volume_number> is the number associated with the boot volume that you want to
extend the partition for.
5. Run the following command to extend the partition:
extend size=<increased_size_in_MB>
<increased_size_in_MB> is the size in MB that you want to extend the partition to.
Warning
6. To confirm that the partition was extended, run the following command and verify that
the boot volume's partition has been extended:
list volume
If a boot volume has been detached from the associated instance, or if the instance is stopped
or terminated, you can attach the boot volume to another instance as a data volume. For
steps, see Attaching a Volume.
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: The policy in Let users launch Compute instances includes the ability to
attach and detach existing block volumes. The policy in Let volume admins manage block
volumes, backups, and volume groups lets the specified group do everything with block
volumes and backups, but not launch instances.
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
1. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Instances.
2. Click the instance that you want to reattach the boot volume to.
3. Under Resources, click Boot Volume.
4. Click the Actions icon (three dots), and then click Attach Boot Volume. Confirm when
prompted.
You can start the instance when the boot volume's status is Attached.
l AttachBootVolume
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.
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: The policy in Let users launch Compute instances includes the ability to
list volumes. The policy in Let volume admins manage block volumes, backups, and volume
groups lets the specified group do everything with block volumes and backups, but not launch
instances.
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
1. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Boot Volumes.
2. Choose your Compartment.
The instance associated with the boot volume is listed in the Attached Instance field. If the
value for this field displays:
None in this Compartment.
the boot volume has been detached from the associated instance, or the instance has been
terminated while the boot volume was preserved.
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.
l ListBootVolumes
l GetBootVolume
There are two ways you can initiate a boot volume backup, the same as block volume
backups. You can either manually start the backup, or assign a policy which defines a set
backup schedule. See Manual Backups and Policy-Based Backups for more information.
The Block Volume service supports the same backups types for boot volumes as for block
volumes:
l Incremental: This backup type includes only the changes since the last backup.
l Full: This backup type includes all changes since the volume was created.
You can restore a boot volume from any of your incremental or full boot volume backups.
Both backup types enable you to restore the full boot volume contents to the point-in-time
snapshot of the boot volume when the backup was taken. You don't need to keep the initial full
backup or subsequent incremental backups in the backup chain and restore them in sequence,
you only need to keep the backups taken for the times you care about.
Note
Tags
When a boot volume backup is created, the source boot volume's tags are automatically
included in the boot volume backup. This also includes boot volumes with custom backup
policies applied to create backups on a schedule. Source boot volume tags are automatically
assigned to all backups when they are created. You can also apply additional tags to volume
backups as needed.
When you create an instance from the boot volume backup, the instance is created includes
the source boot volume's tags.
You can create boot volume backups using the Console or the REST APIs/command line
interface (CLI). See Backing Up a Boot Volume and the BootVolumeBackup API for more
information.
Boot volume backup size may be larger than the source boot volume size. Some of the
reasons for this could include the following:
l Any part of the boot volume that has been written to is considered initialized, so will
always be part of the boot volume backup.
l Many operating systems write or zero out the content, which results in these blocks
marked as used. The Block Volume service considers these blocks updated and includes
them in the volume backup.
l Boot volume backups also include metadata, which can be up to 1 GB in additional data.
For example, in a full backup of a 256 GB Windows boot disk, you may see a backup
size of 257 GB, which includes an additional 1 GB of metadata.
Before you can use a boot volume backup, you need to restore it. For steps, see Restoring a
Boot Volume.
Making a boot volume backup while an instance is running creates a crash-consistent backup,
meaning the data is in the identical state it was in at the time the backup was made. This is
the same state it would be in the case of a loss of power or hard crash. In most cases, you can
restore a boot volume backup and use it to create an instance. Alternatively you can attach it
to an instance as a data volume to repair it or recover data, see Attaching a Volume. To
ensure a bootable image, you should create a custom image from your instance. For
information about creating custom images, see Managing Custom Images.
You can copy boot volume backups between regions using the Console, command line
interface (CLI), SDKs, or REST APIs. For steps, see Copying a Boot Volume Backup Between
Regions. This capability enhances the following scenarios:
To copy boot volume backups between regions, you must have permission to read and copy
boot volume backups in the source region, and permission to create boot volume backups in
the destination region. For more information see Required IAM Policy.
Once you have copied the boot volume backup to the new region you can then restore from
that backup by creating a new volume from the backup using the steps described in Restoring
a Boot Volume.
Consider the following criteria when you decide whether to create a backup or a clone of a
volume.
Volume Supported. You can back up a Supported. You can clone a volume group.
groups volume group.
You can create a backup of a boot volume using the Oracle Cloud Infrastructure Block Volume
service. Boot volume backups are point-in-time snapshots of a boot volume. For more
information about boot volume backups, see Overview of Boot Volume Backups.This topic
describes how to create a manual boot volume backup.
You can also configure a backup policy that creates backups automatically based on a
specified schedule and retention policy. This works the same as block volumes. See Policy-
Based Backups for more information.
For information to help you decide whether to create a backup or a clone of a boot volume,
see Differences Between Boot Volume Backups and Clones.
Note
Warning
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.
Tip
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
1. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Boot Volumes.
2. Click the boot volume that you want to create a backup for.
3. Click Create Manual Backup.
l CreateBootVolumeBackup
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.
For more information about backups, see Overview of Block Volume Backups and Restoring a
Backup to a New Volume.
You can use a boot volume backup to create an instance or you can attach it to another
instance as a data volume. However before you can use a boot volume backup, you need to
restore it to a boot volume.
You can restore a boot volume from any of your incremental or full boot volume backups.
Both backup types enable you to restore the full boot volume contents to the point-in-time
snapshot of the boot volume when the backup was taken. You don't need to keep the initial full
backup or subsequent incremental backups in the backup chain and restore them in sequence,
you only need to keep the backups taken for the times you care about. See Boot Volume
Backup Types for information about full and incremental backup types.
Warning
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.
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
1. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Boot Volume Backups.
2. Choose your Compartment.
3. In the list of boot volume backups, click the Actions icon (three dots) for the boot
volume backup you want to restore and then click Create Boot Volume.
4. Specify a name for the boot volume, select the availability domain to use, and
optionally choose a backup policy for scheduled backups. See Policy-Based Backups for
more information about scheduled backups and volume backup policies.
5. You can restore a boot volume backup to a larger volume size. To do this, check
Custom Block Volume Size (GB) and then specify the new size. You can only
increase the size of the volume, you cannot decrease the size. If you restore the block
volume backup to a larger size volume, you need to extend the volume's partition, see
Extending the Partition for a Boot Volume for more information.
6. Click Create Boot Volume.
The boot volume will be ready to use once its icon no longer lists it as PROVISIONING
in the details page for the boot volume.
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.
To restore a boot volume backup, use the CreateBootVolume operation and specify
BootVolumeSourceFromBootVolumeBackupDetails for CreateBootVolumeDetails.
NEXT S TEPS
After you have restored the boot volume backup, you can:
l Use the boot volume to create an instance, for more information, see Creating an
Instance.
l Attach the boot volume to an instance as a data volume, for more information, see
Attaching a Volume.
Making a boot volume backup while an instance is running creates a crash-consistent backup,
meaning the data is in the identical state it was in at the time the backup was made. This is
the same state it would be in the case of a loss of power or hard crash. In most cases you can
use the restored boot volume to create an instance, however to ensure a bootable image, you
should create a custom image from your instance. For information about creating custom
images, see Managing Custom Images.
You can copy boot volume backups from one region to another region using the Oracle Cloud
Infrastructure Block Volume service. For more information, see Copying Boot Volume
Note
Warning
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: The first two statements listed in the Let volume admins manage block
volumes, backups, and volume groups policy lets the specified group do everything with boot
volumes and boot volume backups with the exception of copying boot volume backups across
regions. The aggregate resource type volume-family does not include the BOOT_VOLUME_
BACKUP_COPY permission, so to enable copying boot volume backups across regions you need
to ensure that you include the third statement in that policy, which is:
Allow group VolumeAdmins to use boot-volume-backups in tenancy where request.permission='BOOT_VOLUME_
BACKUP_COPY'
To restrict access to just creating and managing boot volume backups, including copying boot
volume backups between regions, use the policy in Let boot volume backup admins manage
only backups. The individual resource type boot-volume-backups includes the BOOT_VOLUME_
BACKUP_COPY permission, so you do not need to specify it explicitly in this policy.
If you are copying volume backups encrypted using Vault between regions or you want the
copied volume backup to use Vault for encryption in the destination region, you need to use a
policy that allows the Block Volume service to perform cryptographic operations with keys in
the destination region. For a sample policy showing this, see Let Block Volume, Object
Storage, File Storage, Container Engine for Kubernetes, and Streaming services encrypt and
decrypt volumes, volume backups, buckets, file systems, Kubernetes secrets, and stream
pools.
RESTRICTING ACCESS
The specific permissions needed to copy volume backups across regions are:
SAMPLE POLICIES
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
1. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Boot Volume Backups.
A list of the boot volume backups in the compartment you're viewing is displayed. If you
don’t see the one you're looking for, make sure you’re viewing the correct compartment
(select from the list on the left side of the page).
2. Click the Actions icon (three dots) for the boot volume backup you want to copy to
another region.
3. Click Copy to Another Region.
4. Enter a name for the backup and choose the region to copy the backup to.
5. In the Encryption section select whether you want the boot volume backup to use the
Oracle-provided encryption key or your own Vault encryption key. If you select the
option to use your own key, paste the OCID for encryption key from the destination
region.
6. Click Copy Boot Volume Backup.
7. Confirm that the source and destination region details are correct in the confirmation
dialog and then click OK.
To copy a boot volume backup to another region, use the following operation:
l CopyBootVolumeBackup
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.
NEXT S TEPS
After copying the boot volume backup, switch to the destination region in the Console and
verify that the copied backup appears in the list of boot volume backups for that region. You
can then restore the backup using the steps in Restoring a Boot Volume.
For more information about backups, see Overview of Boot Volume Backups.
A boot volume clone is a point-in-time direct disk-to-disk deep copy of the source boot
volume, so all the data that is in the source boot volume when the clone is created is copied to
the boot volume clone. Any subsequent changes to the data on the source boot volume are not
copied to the boot volume clone. Since the clone is a copy of the source boot volume it will be
the same size as the source boot volume unless you specify a larger volume size when you
create the clone.
The clone operation occurs immediately and you can use the cloned boot volume as soon as
the state changes to available.
There is a single point-in-time reference for a source boot volume while it is being cloned, so
if you clone a boot volume while the associated instance is running, you need to wait for the
first clone operation to complete from the source before creating additional clones. You also
need to wait for any backup operations to complete as well.
You can only create a clone for a boot volume within the same region, availability domain, and
tenant. You can create a clone for a boot volume between compartments as long as you have
the required access permissions for the operation.
Warning
Consider the following criteria when you decide whether to create a backup or a clone of a
volume.
Volume Supported. You can back up a Supported. You can clone a volume group.
groups volume group.
For more information about boot volume backups, see Overview of Boot Volume Backups and
Backing Up a Boot Volume.
1. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Boot Volumes.
2. In the Boot Volumes list, click the boot volume that you want to clone.
3. In Resources, click Boot Volume Clones.
4. Click Create Clone.
5. Specify a name for the clone.
6. If you want to clone the boot volume to a larger size volume, select Custom Boot
Volume Size (GB) and then specify the new size. You can only increase the size of the
volume, you cannot decrease the size. If you clone the boot volume to a larger size
volume, you need to extend the volume's partition. See Extending the Partition for a
Boot Volume for more information.
7. Click Create Clone.
The boot volume is ready use when its icon lists it as AVAILABLE in the Boot Volumes list.
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.
To create a clone from a boot volume, use the CreateBootVolume operation and specify
BootVolumeSourceFromBootVolumeDetails for CreateBootVolumeDetails.
Next Steps
l Use the boot volume to create an instance. For more information, see Creating an
Instance.
l Attach the boot volume to an instance as a data volume. For more information, see
Attaching a Volume.
Making a boot volume clone while an instance is running creates a crash-consistent clone,
meaning the data is in the identical state it was in at the time the clone was made. This is the
same state it would be in the case of a loss of power or hard crash. In most cases you can use
the cloned boot volume to create an instance, however to ensure a bootable image, you
should create a custom image from your instance. For information about creating custom
images, see Managing Custom Images.
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: The policy in Let users launch Compute instances includes the ability to
attach and detach existing block volumes. The policy in Let volume admins manage block
volumes, backups, and volume groups lets the specified group do everything with block
volumes and backups, but not launch instances.
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
You can detach a boot volume from an instance only when the instance is stopped. See
Stopping and Starting an Instance for information about managing an instance's state.
1. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Instances.
2. Choose your Compartment.
3. Click the instance that you want to detach the boot volume from.
4. Under Resources, click Boot Volume.
5. Click the Actions icon (three dots) for the boot volume, and then click Detach Boot
Volume. Confirm when prompted.
You can now attach the boot volume to another instance. For more information, see Attaching
a Volume.
l DetachBootVolume
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
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: The policy in Let volume admins manage block volumes, backups, and
volume groups lets the specified group do everything with block volumes and backups.
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
1. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Boot Volumes.
2. Choose your Compartment.
3. In the Boot Volumes list, find the volume you want to delete.
4. Click the Actions icon (three dots) for the boot volume.
5. Click Terminate and confirm the selection when prompted.
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.
The Block Volume service provides a set of metrics that apply to both boot volumes and block
volumes. For more information, see Block Volume Metrics.
Important
This topic describes how to determine if your Linux-based instance's boot volume is corrupted
and what steps to take to troubleshoot and recover the corrupted boot volume. For Windows
instances, see Recovering a Corrupted Boot Volume for Windows Instances.
Boot volume corruption can prevent an instance from booting successfully, so you may not be
able to connect to the instance using SSH. Instead, you can use the instance console
connection feature to connect to the malfunctioning instance. For more information about
using this feature, see Instance Console Connections.
This section describes how to use a serial console connection to detect if boot volume
corruption has occurred.
Tip
At this point, it's normal for the serial console to appear to hang, as the system may
have already crashed.
3. Reboot the instance from the Console.
4. Once the reboot process starts, switch back to the terminal window, and you should see
system messages from the instance start to appear in the window.
5. Monitor the messages that appear as the system is starting up. Most operating systems
will set the boot volume to read-only as soon as disk corruption is detected to prevent
writes from further corrupting the volume, so look for messages that indicate the boot
volume is in read-only mode. Following are some examples:
l On an instance with iSCSI-attached boot volumes, the iscsiadm service will fail
to attach a volume because the volume is in read-only mode. This will typically
prevent instances from continuing to boot. The serial console may display a
message similar to the following:
iscsiadm: Maybe you are not root?
iscsiadm: Could not lock discovery DB: /var/lock/iscsi/lock.write: Read-only file system
touch: cannot touch `/var/lock/subsys/iscsid': Read-only file system
touch: cannot touch `/var/lock/subsys/iscsi': Read-only file system
The error messages and system behavior described here are the most commonly seen
for boot volume corruption, however depending on the operating system, you may see
different error messages and system behavior. If you don't see the ones described
here, consult the documentation for your operating system for additional
troubleshooting information.
To troubleshoot and recover the corrupted boot volume, you need to detach the boot volume
from the instance and then attach the boot volume to a second instance as a data volume.
If you have detected that your instance's boot volume is corrupted, you need to detach the
boot volume from the instance before you can begin troubleshooting and recovery steps.
For the second instance, we recommend that you use an instance running an operating system
that most closely matches the operating system for the boot volume's instance. You should
only attach boot volumes for Linux-based instances to other Linux-based instances. The
second instance must be in the same availability domain and region as the boot volume's
instance. If no existing instance is available, create a new Linux instance using the steps
described in Creating an Instance. Once you have the second instance, make sure you can log
into the instance and that it is functional before proceeding with the recovery steps. For steps
to access the instance, see Connecting to a Linux Instance. After you have confirmed that the
instance is functional, perform the following steps.
1. Run the lsblk command and make note of the drives that are currently on the instance,
for example:
lsblk
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
sda 8:0 0 46.6G 0 disk
├─sda2 8:2 0 8G 0 part [SWAP]
├─sda3 8:3 0 38.4G 0 part /
└─sda1 8:1 0 200M 0 part /boot/efi
2. Attach the boot volume to the second instance as a data volume. For more information,
see Attaching a Volume.
3. Run the lsblk command again to confirm that the boot volume now shows up as a
volume attached to the instance. In this sample output for the lsblk, the boot volume
attached as a data volume shows up as sdb:
lsblk
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
sdb 8:16 0 46.6G 0 disk
├─sdb2 8:18 0 8G 0 part
├─sdb3 8:19 0 38.4G 0 part
└─sdb1 8:17 0 200M 0 part
sda 8:0 0 46.6G 0 disk
├─sda2 8:2 0 8G 0 part [SWAP]
4. Run the fsck command on the volume's root partition. The root partition is usually the
largest partition on the volume.
The following sample for the fsck command shows the output when there are no errors
or corruption present on the partitions for an Oracle 7.6 instance:
sudo fsck -V /dev/sdb1
fsck from util-linux 2.23.2
[/sbin/fsck.vfat (1) -- /boot/efi] fsck.vfat /dev/sdb1
fsck.fat 3.0.20 (12 Jun 2013)
/dev/sdb1: 17 files, 2466/51145 clusters
If errors are present on a partition, you will usually be prompted to repair the errors.
Following is an example of an interactive repair session of a corrupt ext4 boot volume
for an Ubuntu instance:
sudo fsck -V /dev/sdb1
fsck from util-linux 2.31.1
[/sbin/fsck.ext4 (1) -- /] fsck.ext4 /dev/sdb1
e2fsck 1.44.1 (24-Mar-2018)
One or more block group descriptor checksums are invalid. Fix<y> yes
Group descriptor 92 checksum is 0xe9a1, should be 0x1f53. FIXED.
Pass 1: Checking inodes, blocks, and sizes
Pass 2: Checking directory structure
Note
Important
This topic describes how to determine if your Windows instance's boot volume is corrupted
and what steps to take to troubleshoot and recover the corrupted boot volume. For Linux-
based instances, see Recovering a Corrupted Boot Volume for Linux-Based Instances.
When Windows operating systems detect boot volume corruption, the instance is usually able
to recover from it by automatically repairing the file system. You can use a VNC console
connection to verify that the instance isn't experiencing a system hang while repairing the file
system, or to detect if there are other issues. VNC console connections enable you to see
what's displayed through the VGA port, for more information about the VNC console, see
Instance Console Connections.
Important
Tip
If you have detected that your instance's boot volume is corrupted, you need to detach the
boot volume from the instance before you can begin troubleshooting and recovery steps.
To troubleshoot and recover the corrupted boot volume, you need to attach the boot volume to
a second instance as a data volume. For the second instance we recommend that you use an
instance running an operating system that most closely matches the operating system for the
boot volume's instance, and you should only attach boot volumes for Windows instances to
other Windows instances. The second instance must be in the same availability domain and
region as the boot volume's instance. If no existing instance is available create a new
Windows instance using the steps described in Creating an Instance.
Once you have the second instance, make sure you can log in to the instance and that it is
functional before proceeding with the recovery steps. After you have confirmed that the
instance is functional perform the following steps.
1. Attach the boot volume to the second instance as a data volume. For more information,
see Attaching a Volume.
2. Connect to the second instance, see Connecting to a Windows Instance for more
information.
3. Connect to the volume, see Connecting to a Volume on a Windows Instance for more
information. Since you are attaching a boot volume as a data volume you must also run
the Connect-IscsiTarget and set IsMultiEnabled to true. For example:
Set-Service -Name msiscsi -StartupType Automatic
Start-Service msiscsi
New-IscsiTargetPortal –TargetPortalAddress 169.254.2.4
Connect-IscsiTarget -NodeAddress iqn.2015-02.oracle.boot:uefi -TargetPortalAddress 169.254.2.4 -
IsPersistent $True -IsMultipathEnabled $True
6. Click This PC and then right-click on the new disk and select Properties.
7. Navigate to Tools, Error Checking, and then Check.
8. Select Scan Drive and fix issues as they come up.
9. Mark the new disk Offline.
10. Open iscsi initiator with administrator privileges.
11. In Favorite Targets, remove the iscsi target of the attached volume.
Oracle-Provided Images
An image is a template of a virtual hard drive. The image determines the operating system
and other software for an instance. The following table lists the platform images that are
available in Oracle Cloud Infrastructure. For specific image and kernel version details, along
with changes between versions, see the Oracle-Provided Image Release Notes.
You also can create custom images of your boot disk OS and software configuration for
launching new instances.
l We recommend that you do not reconfigure the firewall on your instance to remove
these rules. Removing these rules allows non-root users or non-administrators to
access the instance’s boot disk volume.
l We recommend that you do not create custom images without these rules unless you
understand the security risks.
l Running Uncomplicated Firewall (UFW) on Ubuntu images might cause issues with these
rules. Because of this, we recommend that you do not enable UFW on your instances.
See Ubuntu Instance fails to reboot after enabling Uncomplicated Firewall (UFW) for
more information.
User Data
Oracle-provided images give you the ability to run custom scripts or supply custom metadata
when the instance launches. To do this, you specify a custom user data script in the
Initialization Script field when you create the instance. For more information about startup
scripts, see cloud-init for Linux-based images and cloudbase-init for Windows-based images.
On Oracle Autonomous Linux images, Oracle Ksplice is installed and configured by default to
run automatic updates.
Note
The Ubuntu image is preconfigured with suitable repositories to allow you to install, update,
and remove packages.
Note
Oracle Linux images on Oracle Cloud Infrastructure include Oracle Linux Premier Support at
no extra cost. This gives you all the services included with Premier Support, including Oracle
Ksplice. Ksplice enables you to apply important security and other critical kernel updates
without a reboot. For more information, see About Oracle Ksplice and Ksplice Overview.
Ksplice is available for Linux instances launched on or after February 15, 2017. For instances
launched before August 25, 2017, you must install Ksplice before running it. See Installing and
Running Oracle Ksplice for more information.
Note
Ksplice Support
You can configure your instance to automatically update to the latest package versions when
the instance first launches using a cloud-init startup script. To do this, add the following code
to the startup script:
package_upgrade: true
The upgrade process starts when the instance launches and runs in the background until it
completes. To verify that it completed successfully, check the cloud-init logs in /var/log.
See User Data and Cloud config examples - Run apt or yum upgrade for more information.
Users
For instances created using Oracle Linux and CentOS images, the username opc is created
automatically. The opc user has sudo privileges and is configured for remote access over the
SSH v2 protocol using RSA keys. The SSH public keys that you specify while creating
instances are added to the /home/opc/.ssh/authorized_keys file.
For instances created using the Ubuntu image, the username ubuntu is created automatically.
The ubuntu user has sudo privileges and is configured for remote access over the SSH v2
protocol using RSA keys. The SSH public keys that you specify while creating instances are
added to the /home/ubuntu/.ssh/authorized_keys file.
Remote Access
Access to the instance is permitted only over the SSH v2 protocol. All other remote access
services are disabled.
Firewall Rules
Instances created using Oracle-provided images have a default set of firewall rules that allow
only SSH access. Instance owners can modify those rules as needed, but must not restrict link
local traffic to address 169.254.0.2 in accordance with the warning at the top of this page.
Be aware that the Networking service uses network security groups and security lists to
control packet-level traffic in and out of the instance. When troubleshooting access to an
instance, make sure all of the following items are set correctly: the network security groups
that the instance is in, the security lists associated with the instance's subnet, and the
instance's firewall rules.
Cloud-init Compatibility
Instances created using Oracle-provided images are compatible with cloud-init. When
launching an instance with the Core Services API, you can pass cloud-init directives with the
metadata parameter. For more information, see LaunchInstance.
For more information about installing and configuring Oracle Autonomous Linux, see Getting
Started: Deploying and Configuring Oracle Autonomous Linux on Oracle Cloud Infrastructure
and Oracle Autonomous Linux for Oracle Cloud Infrastructure.
Do not modify the yum repositories or configurations found in the Oracle Autonomous Linux
image. Any changes to the configuration are unsupported.
Oracle Instant Client 18.3 basic package cannot be updated to Version 19.5 due to changes in
packaging. To update Oracle Instant Client on Oracle Autonomous Linux images that were
launched before March 18, 2020, you must first manually remove the Oracle Instant Client
18.3, and then install 19.5. Use the following commands:
# sudo yum remove oracle-instantclient18.3-basic
# sudo yum install oracle-instantclient19.5-basic
On Oracle Autonomous Linux images that were launched after March 18, 2020, Oracle Instant
Client is not installed by default. To install Oracle Instant Client 19.5, you must manually
install the package. Use the following command:
# sudo yum install oracle-instantclient19.5-basic
For more information about using Oracle Autonomous Linux, see Known Issues.
OCI Utilities
Instances created using Oracle Linux include a preinstalled set of utilities that are designed to
make it easier to work with Oracle Linux images. These utilities consist of a service
component and related command line tools.
The following table summarizes the components that are included in the OCI utilities.
Name Description
ocid The service component of oci-utils. This normally runs as a daemon started via
systemd. This service scans for changes in the iSCSI and VNIC device
configurations and caches the OCI metadata and public IP address of the
instance.
Name Description
oci- Displays metadata for the compute instance. If no command line options are
metadata specified, lists all available metadata. Metadata includes the instance OCID,
display name, compartment, shape, region, availability domain, creation date,
state, image, and any custom metadata that you provide, such as an SSH public
key.
oci- Lists or configures virtual network interface cards (VNICs) attached to the
network- Compute instance. When a secondary VNIC is provisioned in the cloud, it must
config be explicitly configured on the instance using this script or similar commands.
oci- Displays the public IP address of the current system in either human-readable
public- or JSON format.
ip
Windows Editions
Depending on whether you create a bare metal instance or a virtual machine (VM) instance,
different editions of Windows Server are available as Oracle-provided images. Windows
Server Standard edition is available only for VMs. Windows Server Datacenter edition is
available only for bare metal instances.
Users
For instances created using Oracle-provided Windows images, the username opc is created
automatically. When you launch an instance using the Windows image, Oracle Cloud
Infrastructure will generate an initial, one-time password that you can retrieve using the
console or API. This password must be changed after you initially log on.
Remote Access
Firewall Rules
Instances created using the Windows image have a default set of firewall rules that allow
Remote Desktop protocol or RDP access on port 3389. Instance owners can modify these rules
as needed, but must not restrict link local traffic to 169.254.169.253 for the instance to
activate with Microsoft Key Management Service (KMS). This is how the instance stays active
and licensed.
Be aware that the Networking service uses network security groups and security lists to
control packet-level traffic in and out of the instance. When troubleshooting access to an
instance, make sure all of the following items are set correctly: the network security groups
that the instance is in, the security lists associated with the instance's subnet, and the
instance's firewall rules.
On Windows images custom user data scripts are executed using cloudbase-init, which is the
equivalent of cloud-init on Linux-based images. All Oracle-provided Windows images on
Oracle Cloud Infrastructure include cloudbase-init installed by default. When an instance
launches, cloudbase-init runs PowerShell, batch scripts, or additional user data content. See
cloudbase-init Userdata for information about supported content types.
You can use user data scripts to perform various tasks, such as:
l Enable GPU support using a custom script to install the applicable GPU driver.
l Add or update local user accounts.
l Join the instance to a domain controller.
l Install certificates into the certificate store.
l Copy any required application workload files from the Object Storage service directly to
the instance.
Warning
To use WinRM you need to add a stateful ingress security rule for TCP traffic on destination
port 5986. You can implement this security rule in either a network security group that the
instance belongs to, or a security list that is used by the instance's subnet.
Warning
4. Or, to add the rule to a security list that is used by the instance's subnet:
a. Under Resources, click Security Lists. Then click the security list you're
interested in.
b. Click Add Ingress Rules.
c. Enter the following values for the rule:
l Stateless: Leave the check box cleared.
l Source Type: CIDR
l Source CIDR: 0.0.0.0/0
l IP Protocol: TCP
l Source Port Range: All
l Destination Port Range: 5986
l Description: An optional description of the rule.
d. When done, click Add Ingress Rules.
# Options
$opt = New-PSSessionOption -SkipCACheck -SkipCNCheck -SkipRevocationCheck
# Create new PSSession (Pre-requisite: ensure network security group or security list has Ingress
You can now remotely manage the Windows instance from your local PowerShell client.
Here's what you should expect when an OS version reaches the end of its support lifecycle:
l Oracle Cloud Infrastructure no longer provides new images for the OS version. Images
that were previously published are deprecated, and are no longer updated.
l Although you can continue to run instances that use deprecated images, Oracle Cloud
Infrastructure does not provide any support for operating systems that have reached
the end of the support lifecycle.
l If you have an instance that runs an OS version that will be deprecated, and you want to
launch new instances with this OS version after the end of support, you can create a
custom image of the instance and then use the custom image to launch new instances in
the future. For custom Linux images, you must purchase extended support from the OS
vendor. For custom Windows images, see Can I purchase Microsoft Extended Security
Updates for end-of-support Windows OSs?. Oracle Cloud Infrastructure does not provide
any support for custom images that use end-of-support operating systems.
NVIDIA makes available on Oracle Cloud Infrastructure a customized Compute image that is
optimized for the NVIDIA Tesla Volta and Pascal GPUs. Running NGC containers on this
instance provides optimum performance for deep learning jobs.
Warning
Prerequisites
l An Oracle Cloud Infrastructure tenancy. For more information, see Signing Up for
Oracle Cloud Infrastructure.
l A cloud network to launch the instance in. For information about setting up cloud
networks, see Using the Console in VCNs and Subnets.
l A key pair, to use for connecting to the instance via SSH. For information about
generating a key pair, see Managing Key Pairs on Linux Instances.
l Security group and policy configured for the File Storage service. For more information,
see Managing Groups, Getting Started with Policies, and Details for the File Storage
Service.
l An NGC API key for authenticating with the NGC service.
you want to use for SSH access to the instance. Browse to the key file that you want to
upload, or drag and drop the file into the box.
12. Click Create.
You should now see the NGC instance with the status of Provisioning. After the status has
changed to Running, you can connect to the instance. For general information about
launching Compute instances, see Creating an Instance.
See the following topics for steps to access and work with the instance:
l Connecting to an Instance
l Stopping and Starting an Instance
l Terminating an Instance
When you connect to the instance using SSH you will be prompted for the NGC API key. If you
supply the API key at the prompt, the instance will automatically log you into the NGC
container registry so that you can run containers from the registry. You can choose not to
supply the API key at the prompt and still log in to the instance. You can then log in later to the
NGC container registry. See Logging in to the NGC Container Registry for more information.
Oracle Cloud Infrastructure provides a Command Line Interface (CLI) you can use to complete
tasks. For more information, see Quickstart and Configuring the CLI.
Use the launch command to create an instance, specifying image for sourceType and the
image OCID
ocid1.image.oc1..aaaaaaaaknl6phck7e3iuii4r4axpwhenw5qtnnsk3tqppajdjzb5nhoma3q
in InstanceSourceDetails for LaunchInstanceDetails.
You can use the File Storage service for data storage when working with NGC. For more
information, see Overview of File Storage. See the following tasks for creating and working
with the File Storage service:
You can use the Block Volume service for data storage when working with NGC. For more
information, see Overview of Block Volume. See the following tasks for creating and working
with the Block Volume service:
l Creating a Volume
l Attaching a Volume
l Connecting to a Volume
You can also use the CLI to manage block volumes, see the volume commands.
You first need to log into the NGC container registry. You can skip this section if you provided
your API key when logging into the instance via SSH. If you did not provide your API key when
connecting to your instance, then you must perform this step.
At this point you can run Docker commands and access the NGC container registry from the
instance.
1. Pull and run the PyTorch container with the following Docker commands:
docker pull nvcr.io/nvidia/pytorch:17.10
docker run --gpus all --rm -it nvcr.io/nvidia/pytorch:17.10
1. Pull and run the TensorFlow container with the following Docker commands:
docker pull nvcr.io/nvidia/tensorflow:17.10
docker run --gpus all --rm -it nvcr.io/nvidia/tensorflow:17.10
OCI Utilities
Instances created using Oracle-Provided Images based on Oracle Linux include a pre-installed
set of utilities that are designed to make it easier to work with Oracle Linux images. These
utilities consist of a service component and related command line tools that can help with
managing block volumes (attach, remove, and automatic discovery), secondary VNIC
The following table summarizes the components that are included in the OCI utilities.
Name Description
ocid The service component of oci-utils. This normally runs as a daemon started via
systemd. This service scans for changes in the iSCSI and VNIC device
configurations and caches the OCI metadata and public IP address of the
instance.
oci- Expands the root filesystem of the instance to its configured size.
growfs
oci- Displays metadata for the compute instance. If no command line options are
metadata specified, lists all available metadata. Metadata includes the instance OCID,
display name, compartment, shape, region, availability domain, creation date,
state, image, and any custom metadata that you provide, such as an SSH
public key.
oci- Lists or configures virtual network interface cards (VNICs) attached to the
network- Compute instance. When a secondary VNIC is provisioned in the cloud, it must
config be explicitly configured on the instance using this script or similar commands.
oci- Displays the public IP address of the current system in either human-readable
public-ip or JSON format.
The OCI utilities are automatically included with instances launched with an Oracle Linux
image. They are not currently available on other distributions.
Much of the oci-utils functionality requires that you have the Oracle Cloud Infrastructure
SDK for Python and the Oracle Cloud Infrastructure CLI installed and configured.
For configuration information, see the Oracle Cloud Infrastructure SDK for Python
documentation and the documentation for configuring the Oracle Cloud Infrastructure CLI.
To use the OCI utilities, you first need to start the ocid service:
sudo systemctl start ocid.service
Example output:
Redirecting to /bin/systemctl start ocid.service
DESCRIPTION
The ocid daemon is the service component of the oci-utils. It monitors for changes in the
VNIC and iSCSI configuration of the instance and attempts to automatically attach or detach
devices as they appear or disappear - for example, when they are created or deleted using
the Oracle Cloud Infrastructure Console, the command line interface (CLI), or the API.
CONFIGURATION
The ocid daemon requires root privileges. You can configure root privileges for ocid using
one of the following methods:
l Run the oci setup config configuration command as root to create SDK configuration
files for the host. For more information, see SDK and CLI Configuration File.
l Use instance principals by adding the instance to a dynamic group that was granted
access to Oracle Cloud Infrastructure services. For more information, see Managing
Dynamic Groups.
l Configure oci-utils to allow root to use a non-privileged user's Oracle Cloud
Infrastructure configuration files. For more information, see the configuration file
located in the /etc/oci-utils.conf.d directory of the instance.
USAGE
oci-growfs
DESCRIPTION
Expands the root filesystem of the instance to its configured size. This command must be run
as root.
USAGE
OPTIONS
-Y
-N
-H | --HELP
EXAMPLE
# sudo /usr/libexec/oci-growfs
CHANGE: disk=/dev/sda partition=3: start=17188864 old: size=80486399,end=97675263 new:
size=192526302,end=209715166
Confirm? [y/n]: y
CHANGED: disk=/dev/sda partition=3: start=17188864 old: size=80486399,end=97675263 new:
size=192526302,end=209715166
meta-data=/dev/sda3 isize=256 agcount=4, agsize=2515200 blks
= sectsz=4096 attr=2, projid32bit=1
= crc=0 finobt=0 spinodes=0
data = bsize=4096 blocks=10060800, imaxpct=25
= sunit=0 swidth=0 blks
naming =version 2 bsize=4096 ascii-ci=0 ftype=1
log =internal bsize=4096 blocks=4912, version=2
= sectsz=4096 sunit=1 blks, lazy-count=1
realtime =none extsz=4096 blocks=0, rtextents=0
data blocks changed from 10060800 to 24065787
oci-iscsi-config
DESCRIPTION
Lists and configures iSCSI devices attached to a Compute instance running in Oracle Cloud
Infrastructure. When run without any command line options, oci-iscsi-config lists devices
that need attention.
Warning
USAGE
OPTIONS
-I | --INTERACTIVE
Run in interactive mode. This option displays devices that need attention and offers to attach
and configure them. Requires root privileges.
-S | --SHOW
List all devices. If ocid is not running then root privileges are required.
-A | --ATTACH TARGET
Attempt to attach the device with the given IQN (a unique ID assigned to a device) or Oracle
Cloud Identifier (OCID). When using an IQN, the volume must already be attached (assigned)
to the instance in the Console. The Oracle Cloud Infrastructure SDK for Python is required for
selecting volumes using their OCID. This option can be used multiple times to attach multiple
devices at the same time. Requires root privileges.
-D | --DETACH DEVICE
Detach the device with the given IQN (a unique ID assigned to a device). If the volume (or
any partition of the volume) is mounted, this option will attempt to unmount it first. This
option can be used multiple times to detach multiple devices at the same time. Requires root
privileges.
-C | --CREATE-VOLUME SIZE
Create a new volume of SIZE gigabytes and attach it to the current instance. This option
requires the Oracle Cloud Infrastructure SDK for Python to be installed and configured.
--DESTROY-VOLUME OCID
Destroy the block storage volume with the given OCID. The volume must not be attached to
any instances.
Warning
--VOLUME-NAME NAME
Set the display name for the volume. This is used with the --create-volume option.
--USERNAME NAME
Use the specified username as the CHAP username when authentication is needed for
attaching a device. Not needed when the Oracle Cloud Infrastructure SDK for Python is
available.
--PASSWORD PASSWORD
Use the supplied password as the CHAP password when authentication is needed for attaching
a device. This is not needed when the Oracle Cloud Infrastructure SDK for Python is available.
--HELP
EXAMPLES
The oci-iscsi-config utility works with the ocid daemon to monitor device creation and deletion
through the command line, console, or SDK and automatically discover those changes. You
can use the --show option to display a list of all of the devices attached to an instance:
# oci-iscsi-config -s
For full functionality of this utility the ocid service must be running
The administrator can start it using this command:
sudo systemctl start ocid.service
ocid already running.
Currently attached iSCSI devices:
Target iqn.2015-02.oracle.boot:uefi
Persistent portal: 169.254.0.2:3260
Current portal: 169.254.0.2:3260
State: running
Attached device: sda
Size: 46.6G
Partitions: Device Size Filesystem Mountpoint
sda1 544M vfat /boot/efi
sda2 8G swap [SWAP]
sda3 38G xfs /
The following example shows the output of the --show option after adding a 50GB block
volume using the OCI console:
# oci-iscsi-config --show
Currently attached iSCSI devices:
Target iqn.2015-12.com.oracleiaas:abcdefghijklmnopqrstuvwxyz1234567890
Persistent portal: 169.254.2.2:3260
Current portal: 169.254.2.2:3260
State: running
Attached device: sdb
Size: 50G
File system type: Unknown
Mountpoint: Not mounted
Target iqn.2015-02.oracle.boot:uefi
Persistent portal: 169.254.0.2:3260
CREATING A VOLUME
DELETING A VOLUME
oci-metadata
DESCRIPTION
Note
Instance Metadata
USAGE
OPTIONS
-H | --HUMAN-READABLE
-J | --JSON
-G | --GET KEY
--HELP
EXAMPLES
Running oci-metadata with no options returns all metadata for the instance:
# oci-metadata
Instance details:
Display Name: my-example-instance
Region: phx - us-phoenix-1 (Phoenix, AZ, USA)
Canonical Region Name: us-phoenix-1
Availability Domain: cumS:PHX-AD-1
Fault domain: FAULT-DOMAIN-3
OCID: ocid1.instance.oc1.phx.exampleuniqueID
Compartment OCID: ocid.compartment.oc1..exampleuniqueID
Instance shape: VM.Standard2.1
Image ID: ocid1.image.oc1.phx.exampleuniqueID
Created at: 1569529065596
state: Running
agentConfig:
managementDisabled: False
monitoringDisabled: False
Instance Metadata:
ssh_authorized_keys: example-key
Networking details:
VNIC OCID: ocid1.vnic.oc1.phx.exampleuniqueID
VLAN Tag: 2392
Private IP address: 10.0.0.16
MAC address: 02:00:17:03:D8:FE
Subnet CIDR block: 10.0.0.0/24
Virtual router IP address: 10.0.0.1
Pass in a key with the --get parameter to retrieve only the metadata for that key:
# oci-metadata --get state
Instance details:
Instance state: Running
oci-network-config
DESCRIPTION
Warning
USAGE
OPTIONS
-S | --SHOW
Show information on all provisioning and interface configuration. This is the default action if
no options are given.
--CREATE-VNIC
Create a new virtual network interface card (VNIC) and attach it to this instance.
--DETACH-VNIC OCID
Detach and delete the VNIC with the given Oracle Cloud Identifier (OCID) or primary IP
address. Cannot be the primary VNIC for the instance.
--ADD-PRIVATE-IP OCID
--DEL-PRIVATE-IP IP_ADDRESS
--PRIVATE-IP IP_ADDRESS
Assign the given private IP address to the VNIC. Used with the with the --create-vnic and -
-add-private-ip options,
--SUBNET SUBNET
Used with the with the --create-vnic option. Connects the new VNIC to the specified subnet.
--VNIC-NAME NAME
Used with the with the --create-vnic option. Display name for the new VNIC.
--ASSIGN-PUBLIC-IP
When used with the --create-vnic option, assign a public IP address to the new VNIC.
--VNIC OCID
When used with the --add-private-ip option, assign the private IP address to the given
VNIC
-A | --AUTO | -C | --CONFIGURE
Add IP configuration for VNICs that are not configured and delete IP configuration for VNICs
that are no longer provisioned.
-D | --DECONFIGURE
Deconfigure all VNICs (except the primary). If used with the -e option, only the secondary IP
addresses are deconfigured.
-E IP_ADDRESS VNIC_OCID
-N | -NS FORMAT
When configuring, place interfaces in namespace identified by the given format. Format can
include $nic and $vltag variables.
-R | --SSHD
-X | --EXCLUDE ITEM
Persistently exclude the given item from automatic configuration or deconfiguration. Use the
--include option to include the item again.
-I | --INCLUDE ITEM
Include an item that was previously excluded using the --exclude option in automatic
configuration/deconfiguration.
-Q | --QUIET
-H | --HELP
EXAMPLES
Running the oci-network-config command with no options returns the network configuration of
the current instance:
VNIC configuration for instance my-test-instance-20180622-1222
This example creates a new VNIC named MY_NEW_VNIC and attaches it to the instance:
# sudo oci-network-config --create-vnic --vnic-name MY_NEW_VNIC
Info: creating VNIC: 10.0.0.4
Running oci-network-config with the -s option shows information for the new VNIC:
# sudo oci-network-config -s
VNIC configuration for instance scottb-instance-20180622-1222
VNIC 2: MY_NEW_VNIC
Hostname: scottb-instance-20180622-1222-mynewvnic
OCID: ocid1.vnic.oc1.phx.uniqueID
MAC address: 00:00:00:00:00:02
Public IP address: None
Subnet: Public Subnet cumS:PHX-AD-1 (10.0.0.0/24)
DETACHING A VNIC
To detach a VNIC from the instance, use the --detach-VNIC option. Note that the given
VNIC cannot be the primary VNIC for the instance:
sudo oci-network-config --detach-vnic 00:00:00:00:00:02
oci-network-inspector
DESCRIPTION
USAGE
OPTIONS
-C | --COMPARTMENTOCID
-N | --VCN OCID
-H | --HELP
EXAMPLES
vcn: scottb_vcn
Security List: Default Security List for scottb_vcn
Ingress: tcp 0.0.0.0/0:- ---:22
Ingress: icmp 0.0.0.0/0:- code-4:type-3
Ingress: icmp 10.0.0.0/16:- code-None:type-3
Ingress: tcp 0.0.0.0/0:80 ---:80
Ingress: tcp 0.0.0.0/0:43 ---:43
Ingress: tcp 0.0.0.0/0:- ---:-
Egress : all ---:- 0.0.0.0/0:-
oci-public-ip
DESCRIPTION
Displays the public IP address of the current system in either human-readable or JSON
format.
If the Oracle Cloud Infrastructure SDK is installed, the oci-public-ip utility uses the Oracle
Cloud Infrastructure API to discover the IP address.
If the Oracle Cloud Infrastructure SDK is not installed, the oci-public-ip utility uses the
STUN (Session Traversal Utilities for NAT) protocol to discover IP address. For more
information on STUN, see the STUN Wikipedia article.
USAGE
OPTIONS
-H | --HUMAN-READABLE
-J | --JSON
-G | GET
-S | --SOURCEIP SOURCE_IP
-S | --STUN-SERVER STUN_SERVER
-L | --LIST-SERVERS
--INSTANCE-ID OCID
Display the public IP address of the given instance instead of the current one. Requires the
Oracle Cloud Infrastructure SDK for Python to be installed and configured.
--HELP
EXAMPLES
Running the oci-public-ip command with no options returns the IP address of the current
instance:
# oci-public-ip
Public IP address: 203.0.113.2
You can pass in the OCID of a running instance with the --instance-id option to return the IP
address for that instance:
# oci-public-ip --instance-id ocid1.instance.oc1.phx.example_OCID
Public IP address: 203.0.113.2
LISTING STUN SERVERS
stun.voiparound.com
stun.voipstunt.com
Compute Shapes
A shape is a template that determines the number of CPUs, amount of memory, and other
resources that are allocated to an instance.
This topic provides basic information about the shapes that are available for bare metal
instances, virtual machines (VMs), and dedicated virtual machine hosts.
Note
Flexible Shapes
A flexible shape is a shape with a customizable number of OCPUs. When you create a VM
instance using the flexible shape, you select the number of OCPUs that you need for the
workloads that you will run on the instance. The amount of memory, network bandwidth, and
number of VNICs scale proportionately with the number of OCPUs.
Flexible shapes are supported in the following regions. The availability domain in which you
create an instance using a flexible shape must have flexible shape hardware.
The following Oracle-provided platform images are compatible with flexible shapes. Use an
image that was published in March 2020 (for Linux images) or April 2020 (for Windows
images) or later.
Custom images are also supported, depending on the image. You must add flexible shape
compatibility to the custom image, and then test the image on the flexible shape to ensure
that it actually works on the shape.
l Standard Shapes
l Dense I/O Shapes
l GPU Shapes
l HPC Shapes
Standard Shapes
Designed for general purpose workloads and suitable for a wide range of applications and use
cases. Standard shapes provide a balance of cores, memory, and network resources.
Standard shapes are available with Intel or AMD processors.
l BM.DenseIO1: X5-based dense I/O compute. Processor: Intel Xeon E5-2699 v3. Base
frequency 2.3 GHz, max turbo frequency 3.6 GHz.
X5-based shapes availability is limited to monthly universal credit customers existing
on or before November 9, 2018, in the US West (Phoenix), US East (Ashburn), and
Germany Central (Frankfurt) regions.
l BM.DenseIO2: X7-based dense I/O compute. Processor: Intel Xeon Platinum 8167M.
Base frequency 2.0 GHz, max turbo frequency 2.4 GHz.
GPU Shapes
Designed for hardware-accelerated workloads. GPU shapes include Intel CPUs and NVIDIA
graphics processors.
HPC Shapes
Designed for high-performance computing workloads that require high frequency processor
cores and cluster networking for massively parallel HPC workloads.
l BM.HPC2: X7-based high frequency compute. Processor: Intel Xeon Gold 6154. Base
frequency 3.0 GHz, max turbo frequency 3.7 GHz.
VM Shapes
The following shapes are available for VMs:
l Standard Shapes
l Dense I/O Shapes
l GPU Shapes
Standard Shapes
Designed for general purpose workloads and suitable for a wide range of applications and use
cases. Standard shapes provide a balance of cores, memory, and network resources.
Standard shapes are available with Intel or AMD processors.
l VM.Standard1: X5-based standard compute. Processor: Intel Xeon E5-2699 v3. Base
frequency 2.3 GHz, max turbo frequency 3.6 GHz.
X5-based shapes availability is limited to monthly universal credit customers existing
on or before November 9, 2018, in the US West (Phoenix), US East (Ashburn), and
Germany Central (Frankfurt) regions.
l VM.Standard.B1: X6-based standard compute. Processor: Intel Xeon E5-2699 v4. Base
frequency 2.2 GHz, max turbo frequency 3.6 GHz.
1: Instances are billed for the full amount of memory that you provision. Usable memory is
reduced by up to 256 MB per instance. This difference is due to memory reserved to support
the VM on the hypervisor.
l VM.DenseIO1: X5-based dense I/O compute. Processor: Intel Xeon E5-2699 v3. Base
frequency 2.3 GHz, max turbo frequency 3.6 GHz.
GPU Shapes
Designed for hardware-accelerated workloads. GPU shapes include Intel CPUs and NVIDIA
graphics processors.
(GPU:
1xP100)
(GPU:
1xV100)
(GPU:
2xV100)
(GPU:
4xV100)
1: The difference between billed OCPUs and usable OCPUs is due to OCPUs reserved for
hypervisor use.
This topic describes how to install and configure Ksplice. Ksplice is available for Oracle Linux
instances that were launched on or after February 15, 2017. Ksplice is installed on instances
that were launched on or after August 25, 2017, so you just need to run it on these instances
to install the available Ksplice patches. For instances that were launched before August 25,
2017, you must install Ksplice before running it.
On Oracle Autonomous Linux images, Ksplice is installed and configured by default to run
automatic updates.
<public-ip-address> is your instance IP address that you retrieved from the Console,
see Getting the Instance Public IP Address.
3. Download the Ksplice installation script with the following SSH command:
wget -N https://www.ksplice.com/uptrack/install-uptrack-oc
4. Once the script is downloaded, use the following SSH command to install Ksplice:
sh install-uptrack-oc
Running Ksplice
To run Ksplice, you must connect to your Linux instance using a Secure Shell (SSH)
connection. See Connecting to an Instance for more information.
<public-ip-address> is the instance IP address that you retrieved from the Console, see
Getting the Instance Public IP Address.
2. Run the following SSH commands to sudo to the root:
sudo bash cd
Automatic Updates
Note
You can create a custom image of a bare metal instance's boot disk and use it to launch other
instances. Instances you launch from your image include the customizations, configuration,
and software installed when you created the image.
Custom images do not include the data from any attached block volumes. For information
about backing up volumes, see Backing Up a Volume.
Tip
Warning
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: The policy in Let users launch Compute instances includes the ability to
create and manage images. If the specified group doesn't need to launch instances or attach
volumes, you could simplify that policy to include only manage instance-family, and
remove the statements involving volume-family and virtual-network-family.
Tip
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
system implements a 20-minute timeout, during which you cannot create another image
of the same instance. You can, however, create images of different instances at the
same time.
l Custom images are available to all users authorized for the compartment in which the
image was created.
l Custom images inherit the compatible shapes that are set by default from the base
image.
l The maximum size for importing a custom image is 400 GB.
l The maximum size for custom exported images is 400 GB.
l You cannot create an image of an Oracle Database instance.
l If you use a custom image and update the OS kernel on your instance, you must also
upload the update to the network drive. See OS Kernel Updates for more information.
For information about how to deploy any version of any operating system that is supported by
the Oracle Cloud Infrastructure hardware, see Bring Your Own Image (BYOI).
o Oracle Linux
yum update
o CentOS 7
yum update
o Ubuntu 16.04
apt-get update
apt-get dist-upgrade
l Oracle Linux 6, all CentOS versions, and all Windows versions are not cross-compatible.
l Oracle Autonomous Linux 7 is cross-compatible.
l Oracle Linux 7, Ubuntu 18.04, and Ubuntu 16.04 are cross-compatible. Use the Oracle-
provided images for X6.
The primary device drivers that are different between X5, X6, and X7 hosts are:
Additional updates might be required depending on how you have customized the image.
4. In the Create in Compartment list, select the compartment to create the custom
image in.
5. Enter a Name for the image. You can change the name later, if needed. You cannot use
the name of an Oracle-provided image for a custom image.
6. Show Tagging Options: Optionally, you can apply 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 Custom Image.
To track the progress of the operation, you can monitor the associated work request.
For more information, see Using the Console to View Work Requests.
Note
Note
l CreateImage
l GetImage
l ListImages
l UpdateImage
l DeleteImage
l AddImageShapeCompatibilityEntry
l ListImageShapeCompatibilityEntries
l GetImageShapeCompatibilityEntry
l RemoveImageShapeCompatibilityEntry
licensing requirements for Windows images, see Microsoft Licensing on Oracle Cloud
Infrastructure.
Windows supports two kinds of images: generalized and specialized. Generalized images are
images that have been cleaned of instance-specific information. Specialized images are point-
in-time snapshots of the boot disk of a running instance, and are useful for creating backups
of an instance. Oracle Cloud Infrastructure supports bare metal and VM instances launched
from both generalized and specialized custom Windows images.
Generalized images
Specialized images
A specialized image has an OS disk that is already fully installed, and is essentially a copy of
the original bare metal or VM instance. Specialized images are intended to be used for
backups so that you can recover from a failure. Specialized images are useful when you are
testing a task and may need to roll back to known good configuration. Specialized images are
not recommended for cloning multiple identical bare metal instances or VMs in the same
network because of issues with multiple computers having the same computer name and ID.
When creating a specialized image, you must remember the opc user's password; a new
password is not generated when the instance launches, and it cannot be retrieved from the
console or API.
Warning
Warning
6. Extract the files to C:\Windows\Panther. The following files are extracted into the
Panther folder for all Windows Server versions:
l Generalize.cmd
l Specialize.cmd
l unattend.xml
l Post-Generalize.ps1
7. Optional: If you want to preserve the opc user account, edit C:\Program
Files\bmcs\imageType.json and change the imageTypesetting to custom. A new
password is not created and the password is not retrievable from the console or API.
If you want to configure the generalized image to recreate the opc user account when a
new instance is launched from the image, leave the imageType setting defaulted to
general. The new account's password can be retrieved through the API using
GetInstanceDefaultCredentials.
8. Right-click Generalize.cmd, and then click Run as administrator. Keep in mind the
following outcomes of running this command:
l Your connection to the Remote Desktop client might immediately be turned off
and you will be logged out of the instance. If this does not occur, you should log
out of the instance yourself.
l Because sysprep generalize turns off Remote Desktop, you won't be able to log
in to the instance again.
l Creating a generalized image essentially destroys the instance's functionality.
You should wait for a few minutes before proceeding to the following step to ensure the
generalization process has completed.
9. Create the new image using To create a custom image.
10. After you create an image from an instance that has been generalized, we recommend
that you terminate the instance. Although it may appear to be running, it won't be fully
operable.
Important
You create a specialized image the same way you create other custom images. For steps, see
Managing Custom Images.
Image Import/Export
Oracle Cloud Infrastructure Compute lets you share custom images across tenancies and
regions using image import/export.
Warning
l CentOS 6
l CentOS 7
l Ubuntu 16.04 and later
For more information about Oracle-provided platform images, see Oracle-Provided Images.
For information about the licensing requirements for Windows images, see Microsoft Licensing
on Oracle Cloud Infrastructure.
When importing custom Windows images, ensure that the version you select matches the
Windows image that you imported. Failure to provide the correct version and SKU information
could be a violation of your Microsoft Licensing Agreement.
If you change the time zone from the default setting on Windows VM instances, when the
instance reboots or syncs with the hardware clock, the system time will revert back to the
time for the default time zone. However, the time zone setting will stay set to the new time
zone, so the system clock will be incorrect. You can fix this by setting the HKEY_LOCAL_
MACHINE\SYSTEM\CurrentControlSet\Control\TimeZoneInformation registry key to 1.
Oracle-provided Windows images already have the RealTimeIsUniversal registry key set by
default, but you must set this for any custom Windows images that you import.
You can replicate an image from one region to another region using the Console or API. At a
high level:
1. Export the image to an Object Storage bucket in the same region as the image. For
steps, see Exporting an Image.
2. Copy the image to an Object Storage bucket in the destination region. For steps, see
Copying Objects.
3. Obtain the URL path to the image object. For steps, see To view object details.
4. In the destination region, import the image. Use the URL path as the Object Storage
URL. For steps, see Importing an Image.
You can replicate an image from one tenancy to another tenancy using the Console or API. At
a high level:
1. Export the image to an Object Storage bucket in the same region as the image. For
steps, see Exporting an Image.
2. Create a pre-authenticated request with read-only access for the image in the
destination region. For steps, see Working with Pre-Authenticated Requests.
3. In the destination tenancy, import the image. Use the pre-authenticated request URL as
the Object Storage URL. For steps, see Importing an Image.
For example:
https://objectstorage.us-phoenix-1.oraclecloud.com/n/MyNamespace/b/MyBucket/o/MyCustomImage.qcow2
Pre-Authenticated Requests
When using import/export across tenancies, you need to use an Object Storage pre-
authenticated request. See Working with Pre-Authenticated Requests for steps to create a
pre-authenticated request. When you go through these steps, after you click Create Pre-
Authenticated Request, the Pre-Authenticated Request Details dialog box opens. You
must make a copy of the pre-authenticated request URL displayed here, because this is the
only time this URL is displayed. This is the Object Storage URL that you specify for
import/export.
Note
Exporting an Image
You can use the Console or API to export images, and the exported images are stored in the
Oracle Cloud Infrastructure Object Storage service. To perform an image export, you need
write access to the Object Storage bucket for the image. For more information, see Overview
of Object Storage and Let users write objects to Object Storage buckets.
1. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Custom Images.
2. Click the custom image that you're interested in.
3. Click Export.
4. Specify the Object Storage location to export the image to:
l Export to an Object Storage bucket: Select a bucket and enter a name for
the exported image.
l Export to an Object Storage URL: Enter the Object Storage URL.
5. Click Export Image.
After you click Export Image, the image status changes to EXPORTING. You can still launch
instances while the image is exporting, but you can't delete the image until the export has
finished. To track the progress of the operation, you can monitor the associated work request.
For more information, see Using the Console to View Work Requests.
When the export is complete, the image status changes to AVAILABLE. If the image status
changes to AVAILABLE, but you don't see the exported image in the Object Storage location
you specified, this means that the export failed, and you will need to go through the steps
again to export the image.
Importing an Image
You can use the Console or API to import exported images from Object Storage. To import an
image, you need read access to the Object Storage object containing the image. For more
information, see Let users download objects from Object Storage buckets.
1. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Custom Images.
2. Click Import Image.
3. In the Create in Compartment list, select the compartment that you want to import
the image to.
4. Enter a Name for the image.
5. Select the Operating System:
l For Linux images, select Linux.
l For Windows images, select Windows. Select the Operating System Version,
and then certify that the selected operating system complies with Microsoft
licensing agreements.
After you click Import Image, you'll see the imported image in the Custom Images list for
the compartment, with a status of IMPORTING. To track the progress of the operation, you
can monitor the associated work request. For more information, see Using the Console to
View Work Requests.
When the import completes successfully, the status changes to AVAILABLE. If the status
does not change, or no entry appears in the Custom Images list, the import failed. If the
import failed, ensure you have read access to the Object Storage object, and that the object
contains a supported image.
l ListImageShapeCompatibilityEntries
l GetImageShapeCompatibilityEntry
l RemoveImageShapeCompatibilityEntry: Removes a shape from the compatible shapes
list for the image.
o CentOS 7
yum update
o Ubuntu 16.04
apt-get update
apt-get dist-upgrade
l Oracle Linux 6, all CentOS versions, and all Windows versions are not cross-compatible.
l Oracle Autonomous Linux 7 is cross-compatible.
l Oracle Linux 7, Ubuntu 18.04, and Ubuntu 16.04 are cross-compatible. Use the Oracle-
provided images for X6.
The primary device drivers that are different between X5, X6, and X7 hosts are:
Additional updates might be required depending on how you have customized the image.
Note
Licensing Requirements
You can import Windows and Linux-based custom images and use them to launch VMs on
Oracle Cloud Infrastructure. Bringing your own image to a bare metal instance is not
supported.
l Windows images
These Windows versions support custom image import:
o Windows Server 2008 R2 Standard, Enterprise, Datacenter
o Windows Server 2012 Standard, Datacenter
o Windows Server 2012 R2 Standard, Datacenter
o Windows Server 2016 Standard, Datacenter
o Windows Server 2019 Standard, Datacenter
For steps to import a Windows image, see Importing Custom Windows Images.
Oracle Cloud Infrastructure will issue a Microsoft Windows Server license when you
launch an instance using a custom image. Bring your own license (BYOL) for Windows
Server is not permitted. For more information about the licensing requirements for
Windows images, see Microsoft Licensing on Oracle Cloud Infrastructure and Licensing -
Windows Server.
l Linux images
These Linux distributions support custom image import:
5.0.10, Emulated
6.0, 7
12.04 Emulated
Note
You can bring your own operating system images or older operating systems, such as Ubuntu
6.x, RHEL 3.x, and CentOS 5.4, using KVM on bare metal instances.
To bring your own KVM, first create a bare metal instance using the KVM image from
Marketplace. Then, copy your on-premises guest OS to KVM on the bare metal instance.
l Getting Started: Oracle Linux KVM Image for Oracle Cloud Infrastructure
l Installing and Configuring KVM on Bare Metal Instances with Multi-VNIC
You can bring your own operating system images or older operating systems, such as
Windows Server 2003 and Windows Server 2008, using Hyper-V on bare metal instances.
To bring your own Hyper-V, first create a bare metal instance using the Oracle-provided
Windows Server Datacenter platform image. Oracle Cloud Infrastructure will issue a license
for Windows Server when the instance is launched. Then, copy your on-premises guest OS to
Hyper-V on the bare metal instance.
l Bring your own license (BYOL) for Windows Server is not permitted. Oracle Cloud
Infrastructure will issue a license when you launch an instance using a custom image.
For more information about deploying Hyper-V, see Deploying Hyper-V on Oracle Cloud
Infrastructure.
For information about the licensing requirements for Windows images, see Microsoft Licensing
on Oracle Cloud Infrastructure.
Warning
Note
Before you can import a custom Windows image, you must prepare the image to ensure that
instances launched from the image can boot correctly and that network connections will work.
You can perform the tasks described in this section on the running source system. If you have
concerns about modifying the live source system, you can export the image as-is, import it
into Oracle Cloud Infrastructure, and then launch an instance based on the custom image. You
can then connect to the instance using the VNC console and perform the preparation steps.
Important
1. Follow your organization's security guidelines to ensure that the Windows system is
secured. This can include, but is not limited to the following tasks:
l Install the latest security updates for the operating system and installed
applications.
l Enable the firewall, and configure it so that you only enable the rules which are
needed.
l Disable unnecessary privileged accounts.
l Use strong passwords for all accounts.
2. Configure Remote Desktop Protocol (RDP) access to the image:
a. Enable Remote Desktop connections to the image.
b. Modify the Windows Firewall inbound port rule to allow RDP access for both
Private and Public network location types. When you import the image, the
Windows Network Location Awareness service will identify the network
connection as a Public network type.
3. Determine whether the current Windows license type is a volume license by running the
following command in PowerShell:
Get-CimInstance -ClassName SoftwareLicensingProduct | where {$_.PartialProductKey} | select
ProductKeyChannel
If the license is not a volume license, after you import the image, you will update the
license type.
4. If you plan to launch the imported image on more than one VM instance, create a
generalized image of the boot disk. A generalized image is cleaned of computer-specific
information, such as unique identifiers. When you create instances from a generalized
image, the unique identifiers are regenerated. This prevents two instances that are
created from the same image from colliding on the same identifiers.
5. Create a backup of the root volume.
6. If the VM has remotely attached storage, such as NFS or block volumes, configure any
services that rely on this storage to start manually. Remotely attached storage is not
available the first time that an imported instance boots on Oracle Cloud Infrastructure.
7. Ensure that all network interfaces use DHCP, and that the MAC address and IP
addresses are not hardcoded. See your system documentation for steps to perform
network configuration for your system.
8. Download the Oracle Windows VirtIO drivers:
a. Log in to the Oracle Software Delivery Cloud site.
b. In the All Categories list, select Release.
c. Type Oracle Linux 7.6 in the search box and click Search.
d. Add REL: Oracle Linux 7.6.x to your cart, and then click Checkout.
e. In the Platforms/Languages list, select x86 64 bit. Click Continue.
f. Accept the license agreement and then click Continue.
g. Select the check box next to Oracle VirtIO Drivers Version for Microsoft
Windows 1.1.4. Clear the other check boxes.
h. Click Download and then follow the prompts.
Importing a Windows-Based VM
After you prepare a Windows image for import, follow these steps to import the image:
1. Upload the image file to an Object Storage bucket. You can upload the file using the
Console or using the command line interface (CLI). If you use the CLI, use the following
command:
oci os object put -bn <destination_bucket_name> --file <path_to_the_VMDK_or_QCOW2_file>
2. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Custom Images.
3. Click Import Image.
4. In the Create in Compartment list, select the compartment that you want to import
the image to.
5. Enter a Name for the image.
6. For the Operating System, select Windows.
7. In the Operating System Version list, select the version of Windows.
8. Confirm that you chose the operating system version that complies with your Microsoft
licensing agreement, and then select the compliance check box.
Important
14. Show Tagging Options: Optionally, you can apply 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.
15. Click Import Image.
The imported image appears in the Custom Images list for the compartment, with a
status of IMPORTING. When the import completes successfully, the status changes to
AVAILABLE.
If the status doesn't change, or no entry appears in the Custom Images list, the
import failed. Ensure that you have read access to the Object Storage object, and that
the object contains a supported image.
16. Complete the post-import tasks.
1. If you want to use the image on AMD or X6-based shapes, add the shapes to the image's
list of compatible shapes.
2. Create an instance based on the custom image. For the image source, select Custom
Images, and then select the image that you imported.
3. Enable Remote Desktop Protocol (RDP) access to the Compute instance.
4. Connect to the instance using RDP.
5. If the instance requires any remotely attached storage, such as block volumes or file
storage, create and attach it.
6. Create and attach any required secondary VNICs.
7. Test that all applications are working as expected.
8. Reset any services that were set to start manually.
9. Register the instance with the Oracle-provided Key Management Service (KMS) server:
a. On the instance, open PowerShell as Administrator.
b. To set the KMS endpoint, run the following command:
slmgr /skms 169.254.169.253:1688
c. If the Windows license type that you noted while preparing the image isn't a
volume license, you must update the license type. Run the following command:
slmgr /ipk <setup key>
<setup key> is the KMS client setup key that corresponds to the version of
Windows that you imported:
Warning
You can launch imported Linux VMs in either paravirtualized mode or emulated mode. On AMD
shapes, imported images are supported in paravirtualized mode only.
Paravirtualized mode offers better performance than emulated mode. We recommend that
you use paravirtualized mode if your OS supports it. Linux-based operating systems running
the kernel version 3.4 or later support paravirtualized drivers. You can verify your system's
kernel version using the uname command.
The kernel version is the number at the first part of output string. In the sample output shown
previously, the version is 4.14.35.
12.04 Emulated
Note
Tip
We recommend that you enable certificate-based SSH, however this is optional. If you want
your image to automatically use SSH keys supplied from the User Data field when you
launch an instance, you can install cloud-init when preparing the image. See Creating an
Instance for more information about providing user data.
Before you import a custom Linux image, you must prepare the image to ensure that
instances launched from the image can boot correctly and that network connections will work.
Do the following:
1. Optionally, configure your Linux image to support serial console connections. A console
connection can help you remotely troubleshoot malfunctioning instances, such as an
imported image that does not complete a successful boot.
2. Create a backup of the root volume.
3. If the VM has remotely attached storage, such as NFS or block volumes, configure any
services that rely on this storage to start manually. Remotely attached storage is not
available the first time that an imported instance boots on Oracle Cloud Infrastructure.
4. Ensure that all network interfaces use DHCP, and that the MAC address and IP
addresses are not hardcoded. See your system documentation for steps to perform
network configuration for your system.
5. Stop the VM.
6. Clone the stopped VM as a VMDK or QCOW2 file, and then export the image from your
virtualization environment. See the tools documentation for your virtualization
environment for steps.
Importing a Linux-Based VM
After you prepare a Linux image for import, follow these steps to import the image:
1. Upload the image file to an Object Storage bucket. You can upload the file using the
Console or using the command line interface (CLI). If you use the CLI, use the following
command:
oci os object put -bn <destination_bucket_name> --file <path_to_the_VMDK_or_QCOW2_file>
2. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Custom Images.
3. Click Import Image.
4. In the Create in Compartment list, select the compartment that you want to import
the image to.
5. Enter a Name for the image.
6. For the Operating System, select Linux.
7. Select the Import from an Object Storage bucket option.
8. Select the Bucket that you uploaded the image to.
9. In the Object Name list, select the image file that you uploaded.
10. For the Image Type, select the file type of the image, either VMDK or QCOW2.
11. Depending on your image's version of Linux, in the Launch Mode area, select
Paravirtualized Mode or Emulated Mode. If your image supports paravirtualized
drivers, we recommend that you select paravirtualized mode.
12. Show Tagging Options: Optionally, you can apply 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.
13. Click Import Image.
The imported image appears in the Custom Images list for the compartment, with a
status of IMPORTING. When the import completes successfully, the status changes to
AVAILABLE.
If the status doesn't change, or no entry appears in the Custom Images list, the
import failed. Ensure that you have read access to the Object Storage object, and that
the object contains a supported image.
14. Complete the post-import tasks.
1. If you want to use the image on AMD or X6-based shapes, add the shapes to the image's
list of compatible shapes.
2. Create an instance based on the custom image. For the image source, select Custom
Images, and then select the image that you imported.
3. Connect to the instance using SSH.
4. If the instance requires any remotely attached storage, such as block volumes or file
storage, create and attach it. If you are using iSCSI attachments, see Recommended
iSCSI Initiator Parameters for Linux-based Images.
5. Create and attach any required secondary VNICs.
6. Test that all applications are working as expected.
7. Reset any services that were set to start manually.
8. If you enabled serial console access to the image, test it by creating a serial console
connection to the instance.
See the current issues and workarounds for known issues with imported custom images.
You can configure your custom Linux image to support connections using the serial console
feature in the Compute service.
For more information about serial console connections, and steps to troubleshoot if your
image has network connectivity issues after it is launched, see Instance Console Connections.
The serial console connection in Oracle Cloud Infrastructure uses the first serial port, ttyS0,
on the VM. The boot loader and the operating system should be configured to use ttyS0 as a
console terminal for both input and output.
The steps to configure the boot loader to use ttyS0 as a console terminal for both input and
output depend on the GRUB version. Run the following command on the operating system to
determine the GRUB version:
grub install --version
If the version number returned is 2.x, use the steps for GRUB 2. For earlier versions, use the
steps for GRUB.
To configure GRUB2
1. Run the following command to modify the GRUB configuration file:
sudo vi /etc/default/grub
To configure GRUB
1. Run the following command to modify the GRUB configuration file:
sudo vi /boot/grub/grub.conf
The operating system may already be configured to use ttyS0 as a console terminal for both
input and output. To verify, run the following command:
sudo vi /etc/securetty
Check the file for ttyS0. If you don't see it, append ttyS0 to the end of the file.
After completing the steps to enable serial console access to the image, you should validate
that serial console access is working by testing the image with serial console in your
virtualization environment. Consult the documentation for your virtualization environment for
steps to do this. Verify that the boot output displays in the serial console output and that there
is interactive input after the image has booted.
If no output is displayed on the serial console, verify in the configuration for your
virtualization environment that the serial console device is attached to the first serial port.
If the serial console displays output, but there is no interactive input available, check that
there is a terminal process listening on the ttyS0 port. To do this, run the following command:
ps aux | grep ttyS0
This command should output a terminal process that is listening on the ttyS0 port. For
example, if your system is using getty, you will see the following output:
/sbin/getty ttyS0
If you don't see this output, it is likely that a login process is not configured for the serial
console connection. To resolve this, enable the init settings, so that a terminal process is
listening on the ttyS0 at startup.
For example, if your system is using getty, add the following command to the init settings to
run on system startup:
getty -L 9600 ttyS0 vt102
The steps to do this will vary depending on the operating system, so consult the
documentation for the image's operating system.
OS Kernel Updates
Note
Oracle Cloud Infrastructure boots each instance from a network drive. This configuration
requires additional actions when you update the OS kernel.
Oracle Cloud Infrastructure uses Unified Extensible Firmware Interface (UEFI) firmware and a
Preboot eXecution Environment (PXE) interface on the host server to load iPXE from a Trivial
File Transfer Protocol (TFTP) server. The iPXE implementation runs a script to boot Oracle
Linux. During the boot process, the system downloads the kernel, the initrd file, and the
kernel boot parameters from the network. The instance does not use the host's GRUB boot
loader.
Normally, the yum update kernel-uek command edits the GRUB configuration file, either
grub.cfg or grub.conf, to configure the next boot. Since bare metal instances do not use the
GRUB boot loader, changes to the GRUB configuration file are not implemented. When you
update the kernel on your instance, you also must upload the update to the network to ensure
a successful boot process. The following approaches address this need:
l Instances launched from an Oracle-provided image include an Oracle yum plug-in that
seamlessly handles the upload when you run the yum update kernel-uek command.
l If you use a custom image based on an Oracle-provided image, the included yum plug-
in will continue to work, barring extraordinary changes.
l If you install your own package manager, you must either write your own plug-in or
upload the kernel, initrd, and kernel boot parameters manually.
/usr/share/yum-plugins/kernel-update-handler.py
/etc/yum/pluginconf.d
The plug-in looks for two variables in the /etc/sysconfig/kernel file, UPDATEDEFAULT and
DEFAULTKERNEL. It picks up the updates only when the first variable is set to "yes" and the
DEFAULTKERNEL value matches the kernel being updated. For example:
# UPDATEDEFAULT specifies if new-kernel-pkg should make
# new kernels the default
UPDATEDEFAULT=yes
Oracle-provided images incorporate the Unbreakable Enterprise Kernel (UEK). If you want to
switch to a non-UEK kernel, you must update the DEFAULTKERNEL value to "kernel" before you
run yum update kernel.
Manual Updates
Tip
If you manually upload the updates, there are four relevant URLs:
http://169.254.0.3/kernel
http://169.254.0.3/initrd
http://169.254.0.3/cmdline
http://169.254.0.3/activate
The first three URLs are for uploading files (HTTP request type PUT). The fourth URL is for
activating the uploaded files (HTTP request type POST). The system discards the uploaded
files if they are not activated before the host restarts.
The kernel and initrd are simple file uploads. The cmdline upload must contain the kernel boot
parameters found in the grub.cfg or grub.conf file, depending on the Linux version. The
following example is an entry from the /boot/efi/EFI/redhat/grub.cfg file in Red Hat
Linux 7. The highlighted text represents the parameters to upload.
kernel /boot/vmlinuz-4.1.12-37.5.1.el6uek.x86_64 ro root=UUID=8079e287-53d7-4b3d-b708-c519cf6829c8 rd_
NO_LUKS KEYBOARDTYPE=pc KEYTABLE=us netroot=iscsi:@169.254.0.2::3260:iface1:eth0::iqn.2015-
02.oracle.boot:uefi rd_NO_MD SYSFONT=latarcyrheb-sun16 ifname=eth0:90:e2:ba:a2:e3:80 crashkernel=auto
iscsi_initiator=iqn.2015-02. rd_NO_LVM ip=eth0:dhcp rd_NO_DM LANG=en_US.UTF-8 console=tty0
console=ttyS0,9600 iommu=on
The following command returns what is being uploaded to the cmdline file.
cat /tmp/cmdline
The following commands update the cmdline and initrd files, and then activate the changes.
CKSUM=`md5sum /tmp/cmdline | cut -d ' ' -f 1`
When you connect to an instance using SSH, you provide the path to the key pair file in the
SSH command. You can have as many key pairs as you want, or you can keep it simple and
use one key pair for all or several of your instances.
To create key pairs, you can use a third-party tool such as OpenSSH on UNIX-style systems
(including Linux, Solaris, BSD, and OS X) or PuTTY Key Generator on Windows.
Prerequisites
If you're using a UNIX-style system, you probably already have the ssh-keygen utility
installed. To determine if it's installed, type ssh-keygen on the command line. If it's not
installed, you can download OpenSSH for UNIX from http://www.openssh.com/portable.html
and install it.
If you're using a Windows operating system you will need PuTTY and the PuTTY Key
Generator. Download PuTTY and PuTTYgen from http://www.putty.org and install them.
Argument Description
-b 2048 Generate a 2048-bit key. You don't have to set this if 2048 is
acceptable, as 2048 is the default.
-f <path/root_name> The location where the key pair will be saved and the root
name for the files.
9. Write down the names and location of your public and private key files. You will need
the public key when launching an instance. You will need the private key to access the
instance via SSH.
Now that you have a key pair, you're ready to launch instances as described in Creating an
Instance.
Creating an Instance
Use the steps in this topic to create a bare metal or virtual machine (VM) Compute instance.
Tip
When you create an instance, the instance is automatically attached to a virtual network
interface card (VNIC) in the cloud network's subnet and given a private IP address from the
subnet's CIDR. You can let the IP address be automatically assigned, or you can specify a
particular address of your choice. The private IP address lets instances within the cloud
network communicate with each other. If you've set up the cloud network for DNS, instances
can instead use fully qualified domain names (FQDNs).
If the subnet is public, you can optionally assign the instance a public IP address. A public
IP address is required to communicate with the instance over the internet, and to establish a
Secure Shell (SSH) or Remote Desktop Protocol (RDP) connection to the instance from outside
the cloud network.
Note
Warning
Tip
For administrators: The simplest policy to enable users to create instances is listed in Let
users launch Compute instances. It gives the specified group general access to manage
instances and images, along with the required level of access to attach existing block volumes
to the instances. If the group needs to create block volumes, they'll need the ability to
manage block volumes (see Let volume admins manage block volumes, backups, and volume
groups).
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
If the group needs to create instances based on partner images, they'll need the manage
permission for app-catalog-listing to create subscriptions to images from the Partner Image
catalog. See Let users list and subscribe to images from the Partner Image catalog.
The following table lists the default and supported networking types for VM shapes.
To use paravirtualized networking, you must also use an image that supports paravirtualized
networking. Paravirtualized networking is supported on these Oracle-provided images:
SR-IOV networking is supported on all Oracle-provided images, except for Windows Server
2019 when launched using a VM.Standard2 shape.
You can create an instance that uses a specific networking type instead of the default.
However, depending on compatibility between the shape and image that you choose, the
instance might not launch properly. You can test whether it succeeded by connecting to the
instance. If the connection fails, the networking type is not supported. Relaunch the instance
using a supported networking type.
Prerequisites
l A virtual cloud network (VCN) to launch the instance in. For information about setting up
cloud networks, see Overview of Networking.
l The public key from the SSH key pair that you plan to use when you connect to the
instance using SSH. The key must be in OpenSSH format. For information about how to
generate a key pair, see Managing Key Pairs on Linux Instances.
1. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Instances.
2. Select a Compartment that you have permission to work in.
By default, the instance launches in the current compartment. The other resources that
you choose can come from different compartments.
3. Click Create Instance.
4. Enter a name for the 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
instance.
5. By default, an Oracle Linux 7.x image is used to boot the instance. To select a different
image or a boot volume, in the Image or operating system section, click Change
Image. The following options are available:
l Platform Images: Pre-built images for Oracle Cloud Infrastructure. For more
information about platform images, see Oracle-Provided Images.
l Oracle Images: Pre-built Oracle enterprise images and solutions enabled for
Oracle Cloud Infrastructure.
l Partner Images: Trusted third-party images published by Oracle partners. Click
the down arrow in the row for an image to view additional details about the
image, or to change the image build. For more information, see Overview of
Marketplace and Working with Listings.
l Custom Images: Custom images created or imported into your Oracle Cloud
Infrastructure environment. For more information, see Managing Custom Images.
l Boot Volumes: Boot volumes that are available for creating a new instance in
your Oracle Cloud Infrastructure environment. For more information, see Boot
Volumes.
l Image OCID: Create an instance using a specific version of an image by
providing the image OCID. To determine the image OCID for Oracle-provided
images, see Oracle-Provided Image Release Notes.
Choose an image or boot volume, and then click Select Image or Select Boot
Volume.
6. Click Show Shape, Network and Storage Options.
7. Select the Availability domain that you want to create the instance in.
Note
9. In the Configure networking section, configure the network details for the instance:
l Virtual cloud network compartment: The compartment containing the
network in which to create the instance.
l Virtual cloud network: The network in which to create the instance.
l Subnet compartment: The compartment containing a subnet within the cloud
network to attach the instance to.
l Subnet: A subnet within the cloud network to attach the instance 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 AD-specific or regional (regional ones have "regional" after the
name). We recommend using regional subnets. For more information, see About
Regional Subnets.
l Use network security groups to control traffic: Select this check box to add
the instance's primary VNIC to at least one network security group (NSG) of your
choice. NSGs have security rules that apply only to the VNICs in that NSG. For
more information, see Network Security Groups.
l If the subnet is public, you can optionally assign the instance a public IP address.
A public IP address makes the instance accessible from the internet. Select the
Assign a public IP address option. For more information, see Access to the
Internet.
10. In the Boot volume section, configure the size and encryption options for the
instance's boot volume:
l To specify a custom size for the boot volume, select the Specify a custom boot
volume size check box. Then, enter a custom size from 50 GB to 32 TB. The
specified size must be larger than the default boot volume size for the selected
image. See Custom Boot Volume Sizes for more information.
l For VM instances, you can optionally select the Use in-transit encryption check
box. See Block Volume Encryption for more information. If you are using your
own Vault service encryption key for the boot volume, then this key is also used
for in-transit encryption. Otherwise, the Oracle-provided encryption key is used.
l Boot volumes are encrypted by default, but you can optionally use your own Vault
service encryption key to encrypt the data in this volume. To use the Vault service
for your encryption needs, select the Encrypt this volume with a key that
you manage check box. Then, select the Vault compartment and Vault that
contain the master encryption key you want to use. Also select the Master
encryption key compartment and Master encryption key. For more
information about encryption, see Overview of Vault. If you enable this option,
this key is used for both data at rest encryption and in-transit encryption.
l The Block Volume elastic performance feature lets you change the volume
performance for boot volumes. When you create an instance, its boot volume is
configured with the default volume performance set to Balanced. After you
launch the instance, you can modify the performance setting. For steps to modify
the performance setting, see Changing the Performance of a Volume. For more
information about this feature, see Block Volume Elastic Performance.
11. In the Add SSH keys section, upload the public key (.pub) portion of the key pair that
you want to use for SSH access to the instance. Browse to the key file that you want to
upload, or drag and drop the file into the box. To provide multiple keys, press and hold
down the Command key (on Mac) or the CTRL key (on Windows) while selecting files.
Important
12. (Optional) To configure advanced networking and management settings, click Show
Advanced Options. The following options are available:
l On the Management tab, you can configure the following:
o Choose a compartment for your instance: The compartment that you
want to launch the instance in.
o Choose a fault domain: The fault domain to use for the instance. If you
do not specify the fault domain, the system selects one for you. The fault
domain cannot be changed after you create the instance. If you want to use
a different fault domain, you must terminate the instance and launch a new
instance in the preferred fault domain. For more information, see Fault
Domains and Best Practices for Your Compute Instance.
o Initialization Script: User data to be used by cloud-init to run custom
scripts or provide custom cloud-init configuration. Browse to the file that
you want to upload, or drag and drop the file into the box. The file or script
does not need to be base64-encoded, because the Console performs this
encoding when the information is submitted. For information about how to
take advantage of user data, see the cloud-init documentation. The total
maximum size for user data and other metadata that you provide is 32,000
bytes.
Important
o Tags: Optionally, you can apply 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.
l On the Networking tab, you can configure the following:
o Private IP Address: 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.
After the instance is provisioned, details about it appear in the instance list. To view additional
details, including IP addresses, click the instance name.
When the instance is fully provisioned and running, you can connect to it using SSH as
described in Connecting to an Instance.
You also can attach a volume to the instance, provided the volume is in the same availability
domain. For background information about volumes, see Overview of Block Volume.
For steps to let additional users connect to the instance, see Adding Users on an Instance.
Prerequisites
l A virtual cloud network (VCN) to launch the instance in. For information about setting up
VCNs, see Overview of Networking.
l A VCN security rule that enables Remote Desktop Protocol (RDP) access so that you can
connect to your instance. Specifically, you need a stateful ingress rule for TCP traffic on
destination port 3389 from source 0.0.0.0/0 and any source port. For more information,
see Security Rules. You can implement this security rule in a network security group
that you will add this Windows instance to. Or, you can implement this security rule in a
security list that is used by the instance's subnet.
1. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Instances.
2. Select a Compartment you have permission to work in.
By default, the instance launches in the current compartment. The other resources that
you choose can come from different compartments.
3. Click Create Instance.
4. Enter a name for the 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
instance.
Important
5. In the Image or operating system section, you choose the image that's used to boot
the instance. Click Change Image. The following options are available:
l Platform Images: Pre-built images for Oracle Cloud Infrastructure. For more
information about platform images, see Oracle-Provided Images.
l Oracle Images: Pre-built Oracle enterprise images and solutions enabled for
Oracle Cloud Infrastructure.
l Partner Images: Trusted third-party images published by Oracle partners. Click
the down arrow in the row for an image to view additional details about the
image, or to change the image build. For more information, see Overview of
Marketplace and Working with Listings.
l Custom Images: Custom images created or imported into your Oracle Cloud
Infrastructure environment. For more information, see Managing Custom Images.
l Boot Volumes: Boot volumes that are available for creating a new instance in
your Oracle Cloud Infrastructure environment. For more information, see Boot
Volumes.
l Image OCID: Create an instance using a specific version of an image by
providing the image OCID. To determine the image OCID for Oracle-provided
images, see Oracle-Provided Image Release Notes.
Choose an image or boot volume, and then click Select Image or Select Boot
Volume.
6. Click Show Shape, Network and Storage Options.
7. Select the Availability domain that you want to create the instance in.
Note
l For VM instances, you can optionally select the Use in-transit encryption check
box. See Block Volume Encryption for more information. If you are using your
own Vault service encryption key for the boot volume, then this key is also used
for in-transit encryption. Otherwise, the Oracle-provided encryption key is used.
l Boot volumes are encrypted by default, but you can optionally use your own Vault
service encryption key to encrypt the data in this volume. To use the Vault service
for your encryption needs, select the Encrypt this volume with a key that
you manage check box. Then, select the Vault compartment and Vault that
contain the master encryption key you want to use. Also select the Master
encryption key compartment and Master encryption key. For more
information about encryption, see Overview of Vault.
l The Block Volume elastic performance feature lets you change the volume
performance for boot volumes. When you create an instance, its boot volume is
configured with the default volume performance set to Balanced. After you
launch the instance, you can modify the performance setting. For steps to modify
the performance setting, see Changing the Performance of a Volume. For more
information about this feature, see Block Volume Elastic Performance.
11. Skip the Add SSH keys section. An SSH key pair is only required for Linux instances.
For Windows instances, you connect to the instance using a password. An initial
password will be provided when you finish launching the instance.
12. (Optional) To configure advanced networking and management settings, click Show
Advanced Options. The following options are available:
l On the Management tab, you can configure the following:
o Choose a compartment for your instance: The compartment that you
want to launch the instance in.
o Choose a fault domain: The fault domain to use for the instance. If you
do not specify the fault domain, the system selects one for you. The fault
domain cannot be changed after you create the instance. If you want to use
a different fault domain, you must terminate the instance and launch a new
instance in the preferred fault domain. For more information, see Fault
Warning
o Tags: Optionally, you can apply 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.
l On the Networking tab, you can configure the following:
o Private IP address: 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.
o Hostname: A hostname to be used for DNS within the cloud network.
Available only if the VCN and subnet both have DNS labels. For more
information, see DNS in Your Virtual Cloud Network.
o Launch Options: The networking launch type. Available only for VMs. For
more information, see Recommended Networking Launch Types.
l On the Image tab, you can change the image build. By default, the latest build of
the image is used to create the instance. You can select an older build of the
image that is compatible with the shape you selected. Only compatible image
builds are displayed in the list. You must select a shape before you can change the
image build.
l On the Host tab, you can choose to launch the instance on a dedicated virtual
machine host. This lets you run the instance in isolation, so that it is not running
on shared infrastructure. To do this, select the Launch the virtual machine on
a dedicated host check box, and then select a dedicated virtual machine host
from the drop-down list. Before you can place an instance on a dedicated virtual
machine host, you must create a dedicated virtual machine host in the same
availability domain and fault domain as the instance. You can only place an
instance on a dedicated virtual machine host at the time you create the instance.
For more information, see Dedicated Virtual Machine Hosts.
13. Click Create.
To track the progress of the operation, you can monitor the associated work request.
For more information, see Using the Console to View Work Requests.
After the instance is provisioned, details about it appear in the instance list. To view additional
details, including IP addresses and the initial Windows password, click the instance name.
When the instance is fully provisioned and running, you can connect to it using Remote
Desktop as described in Connecting to an Instance.
You also can attach a volume to the instance, provided the volume is in the same availability
domain. For background information about volumes, see Overview of Block Volume.
For steps to let additional users connect to the instance, see Adding Users on an Instance.
l ListInstances
l LaunchInstance
l GetInstance
l UpdateInstance
l TerminateInstance
l GetInstanceDefaultCredentials
You can also launch instances from images that are published by Oracle partners in the
Partner Image catalog. Use these APIs to work with the Partner Image catalog listings:
l AppCatalogListing
l AppCatalogListingResourceVersion
l AppCatalogListingResourceVersionAgreements
l AppCatalogListingResourceVersionSummary
l AppCatalogListingSummary
l AppCatalogSubscription
An instance configuration is a template that defines the settings to use when creating Compute
instances.
An instance pool is a group of instances within the same region that are created from the
same instance configuration and managed as a group.
Instance Configurations
An instance configuration defines the settings to use when creating Compute instances,
including details such as the base image, shape, and metadata. You can also specify the
associated resources for the instance, such as block volume attachments and network
configuration.
To modify an existing instance configuration, create a new instance configuration with the
desired settings.
l CreateInstanceConfiguration
l DeleteInstanceConfiguration
l GetInstanceConfiguration
l UpdateInstanceConfiguration
l ListInstanceConfigurations
Instance Pools
Instance pools let you create multiple Compute instances from the same instance
configuration, within the same region. They also enable integration with other services, such
as the Load Balancing service and IAM service, making it easier to manage groups of
instances.
You create an instance pool using an existing instance configuration. For steps, see Creating
an Instance Pool.
You can automatically adjust the number of instances in an instance pool based on
performance metrics or a schedule. To do this, you enable autoscaling for the instance pool.
For background information and steps, see Autoscaling.
After you have created an instance pool, you can update the size and attach or detach load
balancers from the Console. To update additional settings, you need to use the CLI, API, or
SDKs.
If you need to update the instance configuration, create a new instance configuration and then
update the instance pool to use the new instance configuration. For more information, see
Updating an Instance Pool.
A cluster network is a special kind of instance pool that is designed for massive, high-
performance computing jobs. For more information, see Managing Cluster Networks.
Warning
The following list describes the different lifecycle states for instance pools.
l Provisioning: When you create an instance pool, this is the first state the instance pool
is in. Instances for the instance pool are being configured based on the specified
instance configuration.
l Starting: The instances are being launched. At this point, the only action you can take
is to terminate the instance pool.
l Running: The instances are created and running.
l Stopping: The instances are in the process of being shut down.
l Stopped: The instances are shut down.
l Scaling: After an instance pool has been created, if you update the instance pool size, it
will go into this state while creating instances (for increases in pool size) or terminating
instances (for decreases in pool size). At this point, the only action you can take is to
terminate the instance pool.
l Terminating: The instances and associated resources are being terminated.
l Terminated: The instance pool, all its instances and associated resources are
terminated.
When working with instance configurations and instance pools, keep the following in mind:
l You can't delete an instance configuration if it is associated with at least one instance
pool.
l You can use the same instance configuration for multiple instance pools. However, an
instance pool can have only one instance configuration associated with it.
l If the instance pool has been in the scaling or provisioning state for an extended period
of time, it might be because the number of instances that were requested has exceeded
your tenancy's service limits for that shape and availability domain. For information
about how to check your service limits, and steps to request a service limit increase,
see Service Limits. If this occurs, you need to terminate the instance pool and re-create
it.
l If you modify the instance configuration for an instance pool, existing instances that are
part of that pool will not change. Any new instances that are created after you modify
the instance configuration will use the new instance configuration. New instances will
not be created unless you have increased the size of the instance pool or terminate
existing instances.
l If you decrease the size of an instance pool, the oldest instances are terminated first.
l CreateInstancePool
l GetInstancePool
l ResetInstancePool
l SoftresetInstancePool
l StartInstancePool
l StopInstancePool
l TerminateInstancePool
l UpdateInstancePool
l ListInstancePools
l ListInstancePoolInstances
l AttachLoadBalancer
l DetachLoadBalancer
l GetInstancePoolLoadBalancerAttachment
You use an instance configuration when you want to create one or more instances in an
instance pool. For background information about instance pools, see Managing Compute
Instances.
You can also use an instance configuration to launch individual instances that are not part of a
pool. To do this, use the SDKs, command line interface (CLI), or API.
In the Console, you create an instance configuration using an existing Compute instance as a
template. If you want to create an instance configuration by specifying a list of configuration
settings, use the SDKs, CLI, or API.
Warning
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: For a typical policy that gives access to instance pools and instance
configurations, see Let users manage Compute instance configurations, instance pools, and
cluster networks.
Tagging Resources
You can add tags to your resources to help you organize them according to your business
needs. You can add tags at the time you create a resource, or you can update the resource
later with the desired tags. For general information about applying tags, see Resource Tags.
information about tagging, see Resource Tags. If you are not sure if you should add
tags, skip this option (you can add tags later) or ask your administrator.
7. Click Create Instance Configuration.
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.
Optionally, you can associate a load balancer with an instance pool. If you do this, when you
add an instance to the instance pool, the instance is automatically added to the load balancer's
backend set . After the instance reaches a healthy state (the instance is listening on the
configured port number), incoming traffic is automatically routed to the new instance. For
background information about the Load Balancing service, see Overview of Load Balancing.
Warning
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: For a typical policy that gives access to instance pools and instance
configurations, see Let users manage Compute instance configurations, instance pools, and
cluster networks.
Important
Tagging Resources
You can add tags to your resources to help you organize them according to your business
needs. You can add tags at the time you create a resource, or you can update the resource
later with the desired tags. For general information about applying tags, see Resource Tags.
By default, the instances in a pool are distributed across all fault domains in a best-effort
manner based on capacity. If capacity isn't available in one fault domain, the instances are
placed in other fault domains to allow the instance pool to launch successfully.
In a high availability scenario, you can require that the instances in a pool are evenly
distributed across each of the fault domains that you specify. When sufficient capacity isn't
available in one of the fault domains, the instance pool will not launch or scale successfully,
and a work request for the instance pool will return an "out of capacity" error. To fix the
capacity error, either wait for capacity to become available, or use the UpdateInstancePool
operation to update the placement configuration (the availability domain and fault domain) for
the instance pool.
Prerequisites
Note
l If you want to associate the instance pool with a load balancer, you need a load
balancer and backend set. For steps to create a load balancer, see Managing Load
Balancers.
1. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Instance Pools.
2. Click Create Instance Pool.
3. In the Create in Compartment list, select the compartment that you want to create
the instance pool in.
4. Enter a name for the instance pool. It doesn't have to be unique, and it cannot be
changed later in the Console (but you can change it with the API).
5. Specify the targeted Number of Instances for the instance pool.
6. To select the instance configuration that you want to use, enter the following:
l Instance Configuration Compartment: The compartment that the instance
configuration is in.
l Instance Configuration: The instance configuration to use.
7. If you want to associate a load balancer with the instance pool, select the Attach a
Load Balancer check box. Then, enter the following:
l Load Balancer Compartment: The compartment that the load balancer is in.
l Load Balancer: The load balancer to associate with the instance pool.
l Backend Set: The name of the backend set on the load balancer to add instances
to.
l Port: The server port on the instances to which the load balancer must direct
traffic. This value applies to all instances that use this load balancer attachment.
l VNIC: The VNIC to use when adding the instance to the backend set. Instances
that belong to a backend set are also called backend servers. The private IP
address is used. This value applies to all instances that use this load balancer
attachment.
For background information about load balancers, see Overview of Load Balancing.
add 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 add
tags, skip this option (you can add tags later) or ask your administrator.
11. Click Create Instance Pool.
To track the progress of the operation, you can monitor the associated work request.
For more information, see Using the Console to View Work Requests.
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.
l CreateInstancePool
l AttachLoadBalancer
l DetachLoadBalancer
l GetInstancePoolLoadBalancerAttachment
Optionally, you can associate a load balancer with an instance pool. If you do this, when you
add an instance to the instance pool, the instance is automatically added to the load balancer's
backend set. After the instance reaches a healthy state (the instance is listening on the
configured port number), incoming traffic is automatically routed to the new instance. For
background information about the Load Balancing service, see Overview of Load Balancing.
To update other settings for an instance pool, use the command line interface (CLI), SDKs, or
REST APIs.
You can automatically adjust the number of instances in an instance pool based on
performance metrics or a schedule. To do this, you enable autoscaling for the instance pool.
For background information and steps, see Autoscaling.
See Managing Compute Instances for more information about instance pools and instance
configurations.
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: For a typical policy that gives access to instance pools and instance
configurations, see Let users manage Compute instance configurations, instance pools, and
cluster networks.
Important
Tagging Resources
You can add tags to your resources to help you organize them according to your business
needs. You can add tags at the time you create a resource, or you can update the resource
later with the desired tags. For general information about applying tags, see Resource Tags.
Instance Pools.
2. Click the name of the instance pool that you're interested in.
3. Click Edit.
4. Specify the updated number of instances for the instance pool, and then click Save
Changes.
When you update the instance pool size, it triggers a scaling event. Keep the following in
mind:
l If the instance pool lifecycle state is RUNNING, the instance pool will create new
instances or terminate existing instances at that time, to match the new size of the
instance pool. Instances are terminated in the order that they were created, first-in,
first-out.
l If the instance pool lifecycle state is STOPPED, for an increase in size, new instances
will be configured for the instance pool, but won't be launched. For a decrease in size,
the instances will be terminated.
To track the progress of the operation, you can monitor the associated work request. For
more information, see Using the Console to View Work Requests.
Important
1. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Instance Pools.
2. Click the name of the instance pool that you're interested in.
3. Under Resources, click Load Balancers.
4. Click Attach a Load Balancer.
5. Enter the following:
l Load Balancer Compartment: The compartment that the load balancer is in.
l Load Balancer: The load balancer to associate with the instance pool.
l Backend Set: The name of the backend set on the load balancer to add instances
to.
l Port: The server port on the instances to which the load balancer must direct
traffic. This value applies to all instances that use this load balancer attachment.
l VNIC: The VNIC to use when adding the instance to the backend set. Instances
that belong to a backend set are also called backend servers. The private IP
address is used. This value applies to all instances that use this load balancer
attachment.
6. Click Attach.
To track the progress of the operation, you can monitor the associated work request.
For more information, see Using the Console to View Work Requests.
To update other instance pool configuration settings, use the CLI, SDKs, or REST APIs. For
information about using the CLI, see Command Line Interface (CLI). 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.
For instance pool configuration settings, such as the instance configuration, display name,
tags, or availability domain selections, use the UpdateInstancePool operation.
To manage the load balancers that are associated with an instance pool, use the
AttachLoadBalancer and DetachLoadBalancer operations.
To update the configuration that is used by an instance pool when creating instances, you can
do either of the following things:
l Create a new instance configuration with the desired settings. You can do this using the
Console. For steps, see Creating an Instance Configuration. To do this using the API, use
the CreateInstanceConfiguration operation.
l Update the existing instance configuration for the instance pool. You can only update the
display name and tags of existing instance configurations. For any other updates, create
a new instance configuration with the settings you want to use. To update the display
name or tags, use the UpdateInstanceConfiguration operation. You cannot use the
Console to update instance configuration settings.
In addition to using the API and Console, you can stop and restart instances using the
commands available in the operating system when you are logged in to the instance. Stopping
an instance using the instance's OS does not stop billing for that instance. If you stop the
instances in an instance pool this way, be sure to also stop the instance pool from the Console
or API.
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: For a typical policy that gives access to instance pools and instance
configurations, see Let users manage Compute instance configurations, instance pools, and
cluster networks.
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
For both VM and bare metal instances, billing depends on the shape that you use to create the
instance:
Stopping an instance using the instance's OS does not stop billing for that instance. If you stop
the instances in an instance pool this way, be sure to also stop the instance pool from the
Console or API.
For more information about Compute pricing, see Compute Pricing. For more information
about how instances running Microsoft Windows Server are billed when they are stopped, see
How am I charged for Windows Server on Oracle Cloud Infrastructure?.
1. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Instance Pools.
2. Click the instance pool that contains the instances that you want to stop or start.
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.
To manage the lifecycle state of the instances in an instance pool, use these operations:
l StartInstancePool
l StopInstancePool
l ResetInstancePool
l SoftresetInstancePool
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: For a typical policy that gives access to instance pools and instance
configurations, see Let users manage Compute instance configurations, instance pools, and
cluster networks.
1. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Instance Configurations.
2. Click the instance configuration that you're interested in.
3. Click Delete, and then confirm when prompted.
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 an autoscaling configuration applies to the instance pool, the autoscaling configuration will
be deleted asynchronously after the pool is deleted. You can also manually delete the
autoscaling configuration.
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: For a typical policy that gives access to instance pools and instance
configurations, see Let users manage Compute instance configurations, instance pools, and
cluster networks.
1. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Instance Pools.
2. Click the instance pool that you're interested in.
3. Click More Actions, and then click Terminate.
4. Enter the name of the instance pool and click Terminate.
To track the progress of the operation, you can monitor the associated work request.
For more information, see Using the Console to View Work Requests.
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.
Autoscaling
Autoscaling lets you automatically adjust the number of Compute instances in an instance
pool. This helps you provide consistent performance for your end users during periods of high
demand, and helps you reduce your costs during periods of low demand.
Note
Warning
When an instance pool scales in, instances are terminated in this order: the number of
instances is balanced across availability domains, and then balanced across fault domains.
Finally, within a fault domain, the oldest instance is terminated first.
An autoscaling configuration includes one or more autoscaling policies. These policies define
the criteria that trigger autoscaling actions and the actions to take. Each autoscaling
configuration can either have one metric-based autoscaling policy, or multiple schedule-based
Metric-Based Autoscaling
In metric-based autoscaling, you choose a performance metric to monitor, and set thresholds
that the performance metric must reach to trigger an autoscaling event. When system usage
meets a threshold, autoscaling dynamically resizes the instance pool in near-real time. As
load increases, the pool scales out. As load decreases, the pool scales in.
Metric-based autoscaling relies on performance metrics that are collected by the Monitoring
service, such as CPU utilization. These performance metrics are aggregated into one-minute
time periods and then averaged across all instances in the instance pool. When three
consecutive values (that is, the average metrics for three consecutive minutes) meet the
threshold, an autoscaling event is triggered.
A cooldown period between metric-based autoscaling events lets the system stabilize at the
updated level. The cooldown period starts when the instance pool reaches the Running state.
Autoscaling continues to evaluate performance metrics during the cooldown period. When the
cooldown period ends, autoscaling adjusts the instance pool's size again if needed.
Schedule-Based Autoscaling
Schedule-based autoscaling is ideal for instance pools where demand behaves predictably
based on a schedule, such a month, date, or time of day. Schedules can be recurring or one-
time. For example:
l An instance pool has heavy use during business hours. The pool has lighter use on
evenings and weekends. You can schedule the pool to scale out on weekday mornings,
and to scale in on weekday evenings.
l An instance pool has high demand on New Years Eve. You can schedule the pool to scale
out every year on December 30, and to scale in on January 2.
l You're releasing a new application that runs in the instance pool, and expect that many
people will start using the application after the public announcement. In advance, you
can schedule the pool to scale out on the day of release.
A schedule-based autoscaling configuration can have multiple autoscaling policies, each with a
different schedule and target pool size. If you want to configure scale-in and scale-out events,
you must create at least two separate policies. One policy defines the target pool size and
schedule for scaling in. The other policy defines the target pool size and schedule for scaling
out.
After a schedule-based autoscaling policy is executed, the instance pool stays at the target
pool size until something else changes the pool size, such as a different autoscaling policy.
However, if you manually change the pool size, schedule-based autoscaling does not readjust
the pool size until the next scheduled autoscaling policy is executed.
You define autoscaling schedules using cron expressions. Autoscaling uses the Quartz cron
implementation. You can use an online cron expression generator to verify your cron
expressions; one example is FREEFORMATTER.
Note
A cron expression is a string composed of six or seven fields that represent the different parts
of a schedule, such as hours or days of the week. Cron expressions use this format:
The following table lists the values and special characters that are allowed for each field.
Second 0 None
Note: When using the API, CLI, or SDKs for autoscaling, you must
specify 0 as the value for seconds, even though other values will
create a valid cron expression. You don't need to provide any value
for seconds when using the Console.
* Indicates all values for a * in the month field means every month.
field.
- Indicates a range of values. 8-17 in the hour field means hours 8 through
17, or 8 a.m. through 5 p.m.
/ Use n/m to indicate 0/20 in the minute field means the minutes 0,
increments. The value 20, and 40.
before the slash is the start
time, and the number after
the slash is the value to
increment by.
L Last day of the week or last L in the day-of-the-month field means January
day of the month. 31, February 28 in non-leap years, and so on.
W The weekday (Monday - 10W means the nearest weekday to the 10th of
Friday) that is nearest to the the month. If the 10th is a Saturday, it means
given day. Friday the 9th. If the 10th is a Sunday, it
means Monday the 11th. If the 10th is a
The value does not cross
Wednesday, it means Wednesday the 10th.
months.
# Use x#n to indicate the nth x 5#2 means the second Thursday of the month.
day of the month.
Use these example cron expressions as a starting point to create your own autoscaling
schedules. Combine each cron expression with a target pool size to create an autoscaling
policy. Then, include one or more autoscaling policies in an autoscaling configuration.
Goal: A one-time schedule with only one scaling event. At 11:00 p.m. on December 31, 2020,
scale an instance pool to 100 instances. You'll need one autoscaling policy.
l Policy 1:
o Target pool size: 100 instances
o Execution time: 11:00 p.m. on the 31st day of December, in 2020
o Cron expression: 0 0 23 31 12 ? 2020
Goal: A one-time schedule with a scale-out event and a scale-in event. At 10:00 a.m. on
March 1, 2021, scale out to 75 instances. At 4 p.m. on March 7, 2021, scale in to 30 instances.
You'll need two autoscaling policies.
Goal: A recurring daily schedule. On weekday mornings at 8:30 a.m., scale out to 10
instances. On weekday evenings at 6 p.m., scale in to two instances. You'll need two
autoscaling policies.
Goal: A recurring weekly schedule. On Tuesdays and Thursdays, scale the pool to 30
instances. On all other days of the week, scale the pool to 20 instances. You'll need two
autoscaling policies.
Goal: A recurring monthly schedule. On all days of the month, set the pool size to 20
instances. On the 15th day of the month, scale out to 40 instances. You'll need two autoscaling
policies.
For administrators: For a typical policy that gives access to autoscaling configurations, see
Let users manage Compute autoscaling configurations.
Tagging Resources
You can apply tags to your resources to help you organize them according to your business
needs. You can apply tags at the time you create a resource, or you can update the resource
later with the desired tags. For general information about applying tags, see Resource Tags.
Prerequisites
l You have an instance pool. Optionally, you can attach a load balancer to the instance
pool.
l For metric-based autoscaling, monitoring is enabled on the instances in the instance
pool, and the Monitoring service is receiving metrics that are emitted by the instance.
l You have sufficient service limits to create the maximum number of instances that you
want to scale to.
f. In the Scaling limits area, specify the number of instances in the instance pool:
l Minimum number of instances: The minimum number of instances that
the pool is allowed to decrease to.
l Maximum number of instances: The maximum number of instances that
the pool is allowed to increase to.
Important
Important
c. In the Execution schedule area, define the schedule for implementing this
autoscaling policy in UTC. Use a Quartz cron expression. For more information
about cron expressions, see About Cron Expressions.
d. To schedule additional scaling events, click + Another Policy and then repeat
the previous steps.
6. When you're finished, click Next.
l Name
l For metric-based autoscaling, the cooldown period between autoscaling actions
1. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Autoscaling Configurations.
2. Click the autoscaling configuration that you're interested in.
3. Click Edit.
4. Make your updates, and then click Save Changes.
l Name
l For metric-based autoscaling:
o Which performance metric triggers an autoscaling action
o The minimum and maximum number of instances
o The initial number of instances that the pool should have immediately after you
update the autoscaling policy
Warning
1. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Autoscaling Configurations.
2. Click the autoscaling configuration that you're interested in.
3. In the Autoscaling Policies area, click Edit.
4. Make your updates, and then click Save Changes.
1. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Autoscaling Configurations.
2. Click the autoscaling configuration that you're interested in.
3. Click Delete, and then confirm when prompted.
Cluster networks are designed for highly demanding parallel computing workloads. For
example:
Cluster networks are built on top of the instance pools feature. Most operations in the instance
pool are managed directly by the cluster network, though you can monitor and add tags to the
underlying instance pool.
For more information about how to access and store the data that you want to process in your
cluster networks, see FastConnect Overview, Overview of File Storage, Overview of Object
Storage, and Overview of Block Volume.
Note
Warning
The availability domain that you create the cluster network in must have cluster network-
capable hardware. Typically, to be able to create the multiple HPC instances that are
contained in a cluster network, you must request a service limit increase.
For administrators: For a typical policy that gives access to cluster networks, see Let users
manage Compute instance configurations, instance pools, and cluster networks.
Important
Tagging Resources
You can apply tags to your resources to help you organize them according to your business
needs. You can apply tags at the time you create a resource, or you can update the resource
later with the desired tags. For general information about applying tags, see Resource Tags.
Prerequisites
Create an instance configuration for the instance pool that is managed by the cluster network.
To do this:
l Shape: Click Change Shape. Select Bare Metal Machine, and then select the
the BM.HPC2.36 shape. For more information about this shape, see Compute
Shapes.
b. Create an instance configuration using the instance that you created in the previous step
as a template.
Optionally, you can delete the instance after you create the instance configuration.
Warning
1. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Cluster Networks.
2. Click the cluster network that you're interested in.
3. Click Terminate, and then confirm when prompted.
To track the progress of the operation, you can monitor the associated work request.
For more information, see Using the Console to View Work Requests.
l CreateClusterNetwork
l GetClusterNetwork
l ListClusterNetworks
l ListClusterNetworkInstances
l UpdateClusterNetwork
l ChangeClusterNetworkCompartment
l TerminateClusterNetwork
You are billed for the dedicated virtual machine host as soon as you create it, but you are not
billed for any of the individual VM instances you place on it. You will still be billed for image
licensing costs if they apply to the image you are using for the VM instances.
For instances launched on a dedicated virtual machine host, all of the VM.Standard2 shapes
are supported. For details about these shapes, see VM Shapes. Most of the Compute service
features for VM instances are supported for instances running on dedicated virtual machine
hosts, however the following features are not supported:
l Instance configurations
l Instance pools
l Autoscaling
Reboot migration is also not supported for dedicated virtual machine hosts. In this scenario,
you need to manually migrate the instance. See Moving an Instance with Manual Migration for
this process.
You can mix VM instances with different shapes on the same dedicated virtual machine host.
This might impact the maximum number of instances you can place on the dedicated virtual
machine host. For more information, see Optimizing Capacity on your Dedicated Virtual
Machine Host.
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: The simplest policy to enable users to work with dedicated virtual
machine hosts is listed in Let users manage Compute dedicated virtual machine hosts. It gives
the specified group access to launch instances on dedicated virtual machine hosts and manage
dedicated virtual machine hosts.
See Let users launch Compute instances on dedicated virtual machine hosts for an example of
a policy that allows users to launch instances on dedicated virtual machine hosts without
giving them full administrator access to dedicated virtual machine hosts.
You must create a dedicated virtual machine host before you can place any instances on it.
When creating the dedicated virtual machine host, you select an availability domain and fault
domain to launch it in. All the VM instances that you place on the host will subsequently be
created in this availability domain and fault domain. You also select a compartment when you
create the dedicated virtual machine host, but you can move the host to a new compartment
later without impacting any of the instances placed on it. You can also create the instances in
a different compartment than the dedicated virtual machine host, or move them to difference
compartments after they have been launched.
It can take up to 15 minutes for the dedicated virtual machine host to be fully created. It must
be in the ACTIVE state before you can launch an instance on it.
To query the current state of a dedicated virtual machine host using the CLI, run the following
command:
oci compute dedicated-vm-host get --dedicated-vm-host-id <dedicatedVMhost_ID>
If you try to delete a dedicated virtual machine host that still has running instances hosted on
it, the delete operation will fail. You need to ensure that all of the instances hosted on it have
been terminated. To check if there are any instances still running on the dedicated virtual
machine host, go to the Details page for the dedicated virtual machine host, and click
Hosted Instances in the Resources section. Perform this step for each compartment in
your tenancy that has instances running on the dedicated virtual machine host. To change the
compartment for the Host Instances list, select a different compartment from the Table
Scope drop-down list.
Before you can delete a dedicated machine host, all of the instances running on it must be
terminated.
To list the instances running on a dedicated virtual machine host using the CLI, run the
following command:
oci compute dedicated-vm-host list --compartment-id <compartment_ID> --dedicated-vm-host-id
<dedicatedVMhost_ID>
Run this command for every compartment in your tenancy that has instances running on the
dedicated virtual machine host that you want to delete.
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.
Use the following operations for working with dedicated virtual machine hosts:
l CreateDedicatedVmHost
l DeleteDedicatedVmHost
l ListDedicatedVmHosts
l ListDedicatedVmHostShapes
l ListDedicatedVmHostInstances
l ListDedicatedVmHostInstanceShapes
l UpdateDedicatedVmHost
l ChangeDedicatedVmHostCompartment
You place an instance on a dedicated virtual machine host at the time that you create the
instance. The steps are the same as creating a regular instance, you just need specify that
you want to create the instance on a dedicated virtual machine host when you create the
instance. See Creating an Instance for the steps to create an instance. Once you get to the
Advanced Options section of the form, using the following steps to place the instance on a
dedicated virtual machine host.
Note
5. Click Create.
If you're using the CLI or REST API to create the instance, pass the dedicated virtual machine
host OCID in the optional parameter dedicatedVmHostId when you use the LaunchInstance
operation. If you try to launch an instance with a shape that requires more capacity than what
is available on the dedicated virtual machine host you are trying to place it on, the launch
operation will fail. To avoid this, you can use the ListDedicatedVmHosts operation and pass
the shape you want to use when launching the instance in the InstanceShapeNameQueryParam
parameter. This will return all the dedicated virtual machine hosts that you can place the
instance on.
The following example demonstrates how to call this operation in the CLI to return all the
dedicated virtual machine hosts with sufficient capacity for you to place an instance launched
using the VM.Standard2.16 shape:
compute dedicated-vm-host list --compartment-id <compartment_ID> --instance-shape-name VM.Standard2.16
To fully meet requirements for some compliance scenarios, you might be required to validate
that your instances are running on a dedicated virtual machine host and not using shared
infrastructure. The Oracle Cloud Infrastructure Audit service provides you with the
functionality to do this. Use the steps described in Viewing Audit Log Events to access the log
events for the dedicated virtual machine host.
The steps described in the To search log events section walk you through how to retrieve
the log events with the data you need to verify that your instances are running on a dedicated
virtual machine host. For this procedure:
l Ensure that you select the dedicated virtual machine host's compartment and not the
compartment for the instances that are hosted on it.
l Use the dedicated virtual machine host's OCID as the search keyword.
After you have retrieved the log events for the dedicated virtual machine host, view the log
event lower-level details, and check the contents of the responsePayload property. This
property should contain the OCIDs for the instances that are running on the dedicated virtual
machine host.
When you place an instance on a dedicated virtual machine host using the Console, only
dedicated virtual machine hosts with sufficient capacity to launch an instance based on the
shape that you have specified are displayed in the Dedicated Virtual Machine Host drop-
down list. If you don't see your dedicated virtual machine host in the list, to understand why,
it can help to understand how instances are launched in this scenario.
When you place instances on a dedicated virtual machine host, Oracle Cloud Infrastructure
launches the instances in a manner to optimize performance. For example, a dedicated virtual
machine host created based on the DVH.Standard2.52 shape has two sockets with 24 cores
configured per socket. Instances are placed so that each instance will only use resources local
to a single physical socket. In scenarios where you are creating and terminating instances
with a mix of shapes, this can result in an inefficient distribution of resources, meaning that
not all OCPUs on a dedicated virtual machine host are available to be used. In this scenario, it
might appear that a dedicated virtual machine has enough OCPUs to launch an additional
instance on it, but the instance will fail to launch because of the distribution of existing
instances.
In this example, if you are launching instances using a shape with 16 OCPUs on a dedicated
virtual machine host, you can only launch a maximum of two instances using that shape. You
cannot launch a third instance with 16 OCPUs, even though the remaining number of OCPUs
showing for the dedicated virtual machine host is 16. You can launch additional instances
using shapes with a smaller number of OCPUs.
When designing your cloud footprint, we recommend that you plan to always launch the
largest instance first.
Connecting to an Instance
You can connect to a running instance by using a Secure Shell (SSH) or Remote Desktop
connection. Most UNIX-style systems include an SSH client by default. To connect to a Linux
instance from a Windows system, you can download a free SSH client called PuTTY from
http://www.putty.org.
For administrators: Here's a more restrictive policy that lets the specified group get the IP
address of existing instances and use power actions on the instances (e.g., stop, start, etc.),
but not launch or terminate instances. The policy assumes the instances and the cloud
network are together in a single compartment (XYZ):
Allow group InstanceUsers to read virtual-network-family in compartment XYZ
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
Prerequisites
You'll need the following information to connect to the instance:
l The public IP address of the instance. You can get the address from the Instance Details
page in the Console. Open the navigation menu. Under Core Infrastructure, go to
Compute and click Instances. Then, select your instance. Alternatively, you can use
the Core Services API ListVnicAttachments and GetVnic operations.
l The default username for the instance. If you used an Oracle-provided Linux, CentOS,
or Windows image to launch the instance, the username is opc. If you used the Ubuntu
image to launch the instance, the username is ubuntu.
l For Linux instances: The full path to the private key portion of the SSH key pair that you
used when you launched the instance. For information about how to generate key pairs,
see Managing Key Pairs on Linux Instances.
l For Windows instances: If you're connecting to the instance for the first time, you will
need the initial password for the instance. You can get the password from the Instance
Details page in the Console.
<private_key> is the full path and name of the file that contains the private key
associated with the instance you want to access.
2. Use the following SSH command to access the instance.
$ ssh –i <private_key> <username>@<public-ip-address>
<private_key> is the full path and name of the file that contains the private key
associated with the instance you want to access.
<username> is the default username for the instance. For Oracle Linux and CentOS
images, the default username is opc. For Ubuntu images, the default username is
ubuntu.
<public-ip-address> is your instance IP address that you retrieved from the Console.
1. Open putty.exe.
2. In the Category pane, expand Window, and then select Translation.
3. In the Remote character set drop-down list, select UTF-8. The default locale setting
on Linux-based instances is UTF-8, and this configures PuTTY to use the same locale.
4. In the Category pane, select Session and enter the following:
l Host Name (or IP address):
<username>@<public-ip-address>
<username> is the default username for the instance. For Oracle Linux and
CentOS images, the default username is opc. For Ubuntu images, the default
username is ubuntu.
<public-ip-address> is your instance public IP address that you retrieved from
the Console
l Port: 22
l Connection type: SSH
5. In the Category pane, expand Connection, expand SSH, and then click Auth.
6. Click Browse, and then select your private key.
7. Click Open to start the session.
If this is your first time connecting to the instance, you might see a message that the
server's host key is not cached in the registry. Click Yes to continue the connection.
To enable Remote Desktop Protocol (RDP) access to the Windows instance, you need to add a
stateful ingress security rule for TCP traffic on destination port 3389 from source 0.0.0.0/0
and any source port. You can implement this security rule in either a network security group
that the Windows instance belongs to, or a security list that is used by the instance's subnet.
Tip
The Oracle Cloud Infrastructure Compute service provides console connections that enable
you to remotely troubleshoot malfunctioning instances, such as:
5. Upload the public key (.pub) portion for the SSH key. You can browse to a public key file
on your computer or paste your public key into the text box.
6. Click Create Console Connection.
When the console connection has been created and is available, the status changes to
ACTIVE.
Note
Note
You connect to the serial console by using an SSH client. Mac OS X and most Linux
distributions by default include the SSH client OpenSSH.
Windows does not include an SSH client by default, so you need to install one. You can use
PuTTY, or there are options that include a version of OpenSSH such as:
The steps to connect to the serial console from the PuTTY client are different from the steps
for OpenSSH.
Warning
After you create the console connection for the instance, you need to set up a secure tunnel to
the VNC server on the instance, and then you can connect with a VNC client.
Note
Note
l BM.GPU2.2
l BM.HPC2.36
l BM.Standard2.52
l BM.DenseIO2.52
l BM.Standard.B1.44
To set up a secure tunnel to the VNC server on the instance using OpenSSH on
Mac OS X or Linux
1. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Instances.
2. Click the instance that you're interested in.
3. Under Resources, click Console Connections.
4. Click the Actions icon (three dots), and then click Copy VNC Connection for
Linux/Mac.
5. Paste the connection string copied from the previous step to a terminal window on a Mac
OS X or Linux system, and then press Enter to set up the secure connection.
6. After the connection is established, open your VNC client and specify localhost as the
host to connect to and 5900 as the port to use.
Note
To set up a secure tunnel to the VNC server on the instance using PowerShell
on Windows
1. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Instances.
2. Click the instance that you're interested in.
3. Under Resources, click Console Connections.
4. Click the Actions icon (three dots), and then click Copy VNC Connection for
Windows.
5. Paste the connection string copied from the previous step to Windows Powershell, and
then press Enter to set up the secure connection.
6. After the connection is established, open your VNC client and specify localhost as the
host to connect to and 5900 as the port to use.
Note
Both of these tasks require you to boot into a bash shell, in maintenance mode.
Note
Console messages start to appear in the window. As soon as you see the GRUB boot
menu appear, use the up/down arrow key to stop the automatic boot process, enabling
you to use the boot menu.
3. In the boot menu, highlight the top item in the menu, and type e to edit the boot entry.
4. In edit mode, use the down arrow key to scroll down through the entries until you reach
the line that starts with either linuxefi for instances running Oracle Autonomous Linux
7.x or Oracle Linux 7.x, or kernel for instances running Oracle Linux 6.x.
5. At the end of that line, add the following:
init=/bin/bash
6. Reboot the instance from the terminal window by entering the keyboard shortcut
CTRL+X.
When the instance has rebooted, you'll see the Bash shell command line prompt, and you can
proceed with either of the following procedures.
2. Run the following command to remount the root partition with read/write permissions:
/bin/mount -o remount, rw /
2. Run the following command to remount the root partition with read/write permissions:
/bin/mount -o remount, rw /
3. From the Bash shell, run the following command to change to the SSH key directory for
the opc user:
cd ~opc/.ssh
4. Rename the existing authorized keys file with the following command:
mv authorized_keys authorized_keys.old
5. Replace the contents of the public key file with the new public key file with the following
command:
echo '<contents of .pub key file>' >> authorized_keys
When you are finished using the console connection, delete the connection for the instance.
If you created your instance using an Oracle-provided Linux or CentOS image, you can use
SSH to access your instance from a remote host as the opc user. If you created your instance
using the Ubuntu image, you can use SSH to access your instance from a remote host as the
ubuntu user. After signing in, you can add users to the instance.
If you created your instance using an Oracle-provided Windows image, you can create new
users after you sign in to the instance through a Remote Desktop client.
Tip
The new users then can SSH to the instance using the appropriate private keys.
7. Copy the SSH public key that you saved to a text file into the /home/new_
user/.ssh/authorized_keys file:
echo <public_key> > /home/<new_user>/.ssh/authorized_keys
8. Change the owner and group of the /home/username/.ssh directory to the new user:
chown -R <new_user>:<group> /home/<new_user>/.ssh
9. To enable sudo privileges for the new user, run the visudo command and edit the
/etc/sudoers file as follows:
a. In /etc/sudoers, look for:
%<username> ALL=(ALL) NOPASSWD: ALL
For administrators: The policy in Let users launch Compute instances includes the ability to
manage console history data. If the specified group doesn't need to launch instances or attach
volumes, you could simplify that policy to include only manage instance-family, and
remove the statements involving volume-family and virtual-network-family.
l CaptureConsoleHistory
l DeleteConsoleHistory
l GetConsoleHistory
l GetConsoleHistoryContent
l ListConsoleHistories
You can find some of this information in the Console on the Instance Details page, or you
can get all of it by logging in to the instance and using the metadata service. The service runs
on every instance and is an HTTP endpoint listening on 169.254.169.254.
For administrators: Users can also get instance metadata through the Compute API (for
example, with GetInstance). The policy in Let users launch Compute instances covers that
ability. If the specified group doesn't need to launch instances or attach volumes, you could
simplify that policy to include only manage instance-family, and remove the statements
involving volume-family and virtual-network-family.
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
Here's an example response that shows of all of the information for an instance:
{
"availabilityDomain": "cumS:PHX-AD-1",
"faultDomain": "FAULT-DOMAIN-2",
"compartmentId": "ocid.compartment.oc1..exampleuniqueID",
"displayName": "my-example-instance",
"hostname": "my-hostname",
"id": "ocid1.instance.oc1.phx.exampleuniqueID",
"image": "ocid1.image.oc1.phx.exampleuniqueID",
"metadata": {
"ssh_authorized_keys": "example-ssh-key"
},
"region": "phx",
"canonicalRegionName": "us-phoenix-1",
"shape": "VM.Standard2.1",
"state": "Running",
"timeCreated": 1569358494495,
"agentConfig": {
"monitoringDisabled": false,
"managementDisabled" : false
},
"definedTags": {
"Operations": {
"CostCenter": "42"
}
},
"freeformTags": {
"Department": "Finance"
}
}
For more information about the data that is returned, see Instance.
Here's an example response that shows the VNICs that are attached to an instance:
[ {
"vnicId" : "ocid1.vnic.oc1.phx.exampleuniqueID",
"privateIp" : "10.0.3.6",
"vlanTag" : 11,
"macAddr" : "00:00:00:00:00:01",
"virtualRouterIp" : "10.0.3.1",
"subnetCidrBlock" : "10.0.3.0/24",
"nicIndex" : 0
}, {
"vnicId" : "ocid1.vnic.oc1.phx.exampleuniqueID",
"privateIp" : "10.0.4.3",
"vlanTag" : 12,
"macAddr" : "00:00:00:00:00:02",
"virtualRouterIp" : "10.0.4.1",
"subnetCidrBlock" : "10.0.4.0/24",
"nicIndex" : 0
} ]
When you create an instance using the LaunchInstance operation, you can specify custom
metadata for the instance in the LaunchInstanceDetails datatype's metadata or
extendedMetadata attributes.
To update an instance's metadata, use the UpdateInstance operation, specifying the custom
metadata in the UpdateInstanceDetails datatype's metadata or extendedMetadata attributes.
The metadata attribute supports key/value string pairs. The extendedMetadata attribute
supports nested JSON objects. The combined size of these two attributes can be a maximum
of 32,000 bytes.
Warning
For administrators: The policy in Let users launch Compute instances includes the ability to
rename an instance. If the specified group doesn't need to launch instances or attach
volumes, you could simplify that policy to include only manage instance-family, and
remove the statements involving volume-family and virtual-network-family.
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
values in that attribute will be used. You cannot specify a value for the same metadata key
twice, this will cause the UpdateInstance operation to fail due to there being duplicate keys.
To understand this, consider the example scenario where you created an instance using the
LaunchInstance operation and specified the following key/value pair for the metadata
attribute:
"myCustomMetadataKey" : "myCustomMetadataValue"
If you then call the UpdateInstance operation, and add new metadata by specifying
additional key/value pairs in the extendedMetadata attribute, but you leave the metadata
attribute empty, do not include the myCustomMetadataKey key/value in the
extendedMetadata attribute, as this will cause the operation to fail since that key already
exists. If you do specify values for the metadata attribute, you need to include the
myCustomMetadataKey key/value to maintain it in the instance's metadata. In this case, you
can specify it in either of the attributes.
There are two reserved keys, user_data and ssh_authorized_keys, that can only be set for
an instance at launch time, they cannot be updated later. If you use the metadata attribute to
add or update metadata to an instance, you need to ensure that you include the values
specified at launch time for both these keys, otherwise the UpdateInstance operation will
fail.
l Use the GetInstance operation to retrieve the existing custom metadata for the instance
to ensure that you include the values you want to maintain in the appropriate attributes
when you call UpdateInstance. The metadata values are returned in the metadata and
extendedMetadata attributes for the Instance . For a code example demonstrating this,
see the UpdateInstanceExample in the SDK for Java.
l Unless you are updating custom metadata that was added using the metadata attribute,
use the extendedMetadata attribute to add custom metadata. Otherwise you need to
include the launch time values for the user_data and ssh_authorized_keys reserved
keys. If you use the metadata attribute to add values and you leave out the values for
these reserved keys or specify different values for them, the UpdateInstance call will
fail.
Renaming an Instance
You can rename an instance without changing its Oracle Cloud Identifier (OCID).
Warning
For administrators: The policy in Let users launch Compute instances includes the ability to
rename an instance. If the specified group doesn't need to launch instances or attach
volumes, you could simplify that policy to include only manage instance-family, and
remove the statements involving volume-family and virtual-network-family.
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
l UpdateInstance
When you change the shape of an instance, you select a different processor, number of cores,
amount of memory, network bandwidth, and maximum number of VNICs for the instance. The
instance's public and private IP addresses, volume attachments, and VNIC attachments
remain the same.
Supported Shapes
The shape series and image of the original shape determine which shapes you can select as a
target for the new shape. You can resize instances that use these shapes:
l VM.Standard.E2.1.Micro series
l VM.DenseIO1 series
l VM.DenseIO2 series
l VM.GPU2 series
l VM instances that run on dedicated virtual machine hosts
l Bare metal shapes
l The image that's used to launch the instance must be compatible with the new shape. To
see which shapes are compatible, do either of the following things: In the Console, on
the Instance Details page, click the name of the image, and then refer to the list of
compatible shapes. Or, using the API, call the ListShapes operation and pass the image
OCID as a parameter. Some Marketplace images cannot be resized because of licensing
constraints.
l Microsoft SQL Server images cannot be resized because of licensing constraints.
l You must have sufficient service limits for the new shape.
l Different shapes are billed at different rates. When you change the shape of an
instance, you are billed to the nearest second of usage for each shape that you use. For
more information, see Compute Pricing and Resource Billing for Stopped Instances.
l If the instance has secondary VNICs configured, you might need to reconfigure them
after the instance is rebooted. For more information, see Virtual Network Interface
Cards (VNICs).
l If the instance is running when you change the shape, it is rebooted as part of the
change shape operation. If the applications that run on the instance take a long time to
shut down, they could be improperly stopped, resulting in data corruption. To avoid this,
shut down the instance using the commands available in the OS before you change the
shape.
l When you change the shape from one hardware series to a different series, some
hardware details such as the network interface name might change. This might cause
problems for some guest OSs, particularly if the OS has been customized. If the OS fails
to boot after you change the shape, then you should change the instance back to the
original shape.
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: The policy in Let users launch Compute instances includes the ability to
change the shape of an instance. If the specified group doesn't need to launch instances or
attach volumes, you could simplify that policy to include only manage instance-family, and
remove the statements involving volume-family and virtual-network-family.
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
Prerequisites
l If you want to change the instance to a smaller shape that supports fewer VNICs, detach
the extra VNICs.
l Intel Skylake: Standard shapes that use the current generation Intel processor
and have a fixed number of OCPUs.
l Specialty and Legacy: Standard shapes with previous generation Intel and AMD
processors.
5. Click Change Shape.
If the instance is running, it is rebooted as part of the change shape operation.
l UpdateInstance
Note
Note
Reboot Migration
For instances with a date in the Reboot Maintenance field (available in the Console, CLI,
and SDKs), you can reboot your instance to move it to new infrastructure. After you reboot
the instance, the Reboot Maintenance field is cleared. This change indicates that the
instance was moved successfully.
l Any public IP addresses assigned to your instance from a reserved public pool are
retained. Any that were not assigned from a reserved public IP address pool will
change. Private IP addresses do not change.
l MAC addresses, CPUIDs, and other unique hardware identifiers do change during the
move. If any applications running on the instance use these identifiers for licensing or
other purposes, be sure to take note of this information before moving the instance to
help you manage the change.
l All private IP addresses, names, and subnets. Note that the instance can have
multiple VNICs, and each VNIC can have multiple secondary IP addresses.
l All private DNS names. The instance can have multiple VNICs, and each VNIC can
have multiple secondary IP addresses. Each private IP address can have a DNS
name.
l Any public IP addresses assigned from a reserved public pool. Note that the
instance can have multiple VNICs, and each VNIC can have multiple secondary
private IP addresses. Each VNIC and secondary private IP address can have an
attached public IP address.
l Any remote block volumes attached to the instance.
l Any tags on the instance or attached resources.
2. Prepare the instance for manual migration:
l Ensure that any remote block volumes defined in /etc/fstab use the
recommended options.
l Ensure that any File Storage service (NFS) mounts use the nofail option.
l If you have statically defined any network interfaces belonging to secondary
VNICs using their MAC addresses, such as those defined in
/etc/sysconfig/network-scripts/ifcfg*, those interfaces will not start due to
the change in the MAC address. Remove the static mapping.
l If you use the Oracle-provided script to configure secondary VNICs, ensure it runs
automatically at startup.
Warning
3. If your instance has local NVMe storage (dense instances), you must back up this data:
a. Create and attach one or more remote block volumes to the instance.
b. Copy the data from the NVMe devices to the remote block volumes.
4. Unmount any remote block volumes or File Storage service (NFS) mounts.
5. Back up all remote block volumes. See Overview of Block Volume Backups for more
information.
6. Create a backup of the root volume.
Important
8. Create a new instance using the boot volume from the terminated instance.
9. In the launch instance flow, specify the private IP address that was attached to the
primary VNIC. If the public IP address was assigned from a reserved IP address pool,
be sure to assign the same IP address.
10. When the instance state changes to RUNNING, Stop the instance.
11. Recreate any secondary VNICs and secondary IP addresses.
12. Attach any remote block volumes.
Note
17. (Optional) After you confirm that the instance and applications are healthy, you can
delete the volume backups.
When you move a Compute resource to a new compartment, associated resources such as
boot volumes and VNICs are not moved.
After you move the resource to the new compartment, inherent policies apply immediately
and affect access to the resource through the Console. For more information, see Managing
Compartments.
For administrators: The following policies allow users to move Compute resources to a
different compartment:
Allow group ComputeCompartmentMovers to manage instance-family in tenancy
If you're new to policies, see Getting Started with Policies and Common Policies.
Note
1. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Instance Configurations.
2. In the List Scope section, select a compartment.
3. Click the instance configuration that you're interested in.
4. Click Move Resource.
5. Choose the destination compartment from the list.
6. Click Move Resource.
b. Update the instance pool with the new instance configuration. You can do this
using the API. For steps, see Updating an Instance Pool.
8. Optionally, move the instances and other resources that are associated with the
instance pool to the new compartment.
Cluster Networks.
2. In the List Scope section, select a compartment.
3. Click the cluster network that you're interested in.
4. Click Move Resource.
5. Choose the destination compartment from the list.
6. Click Move Resource.
7. Optionally, move the instances and other resources that are associated with the cluster
network to the new compartment.
l ChangeInstanceCompartment
l ChangeInstanceConfigurationCompartment
l ChangeInstancePoolCompartment
l ChangeAutoScalingConfigurationCompartment
l ChangeImageCompartment
l ChangeClusterNetworkCompartment
For steps to manage the lifecycle state of instances in an instance pool, see Stopping and
Starting the Instances in an Instance Pool.
For administrators: The policy in Let users launch Compute instances includes the ability to
stop or start an existing instance. If the specified group doesn't need to launch instances or
attach volumes, you could simplify that policy to include only manage instance-family, and
remove the statements involving volume-family and virtual-network-family.
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
limits. To halt billing and remove related resources from your service limits, you must
terminate the instance.
l GPU shapes: Billing continues for stopped instances because GPU resources are
preserved. Related resources continue to count toward your service limits. To halt
billing and remove related resources from your service limits, you must terminate the
instance.
l HPC shapes: Billing continues for stopped instances because the NVMe storage
resources are preserved. Related resources continue to count toward your service
limits. To halt billing and remove related resources from your service limits, you must
terminate the instance.
Stopping an instance using the instance's OS does not stop billing for that instance. If you stop
an instance this way, be sure to also stop it from the Console or API.
For more information about Compute pricing, see Compute Pricing. For more information
about how instances running Microsoft Windows Server are billed when they are stopped, see
How am I charged for Windows Server on Oracle Cloud Infrastructure?.
To identify the VM instances that you can proactively reboot, do any of the following things:
Using the Console: To see which instances in the current compartment are
scheduled for a maintenance reboot
1. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Instances.
If the instance has a maintenance reboot scheduled and can be proactively rebooted, a
warning icon appears next to the instance name.
2. Click the instance that you're interested in, and then check the Maintenance Reboot
field for the instance. This field displays the date and start time for the maintenance
reboot.
Using the API: To see which instances in a compartment are scheduled for a
maintenance reboot
Use the ListInstances operation. The timeMaintenanceRebootDue field for the Instance
returns the date and start time for the maintenance reboot.
Using Search: To find all instances that are scheduled for a maintenance
reboot
1. In the Console, append "/search" to the end of your base Console URL. For example,
https://console.us-ashburn-1.oraclecloud.com/search.
2. Click Select Sample Query, and then click Query for all instances which have an
upcoming scheduled maintenance reboot.
3. Click Search.
When you reboot an instance for maintenance, it is migrated to a different physical VM host.
If you choose not to reboot before the scheduled time, then Oracle Cloud Infrastructure will
reboot and migrate your instances within a 24-hour period after the scheduled time.
Standard and GPU VM instances are recovered to another physical VM host using reboot
migration. During the reboot, instance properties such as private and ephemeral public IP
addresses, attached block volumes, and VNICs are preserved.
Dense I/O VM instances are recovered by rebooting the instance on the same physical host. If
recovering a Dense I/O instance on the same physical host isn't possible, Oracle Cloud
Infrastructure notifies you to terminate the instance within 14 days. If you don't terminate the
instance before the deadline, Oracle Cloud Infrastructure will terminate it. The boot volume
and remote attached data volume are preserved.
However, the following properties do change when a bare metal instance restarts on different
physical hardware: the MAC addresses and the host serial number. You might also notice
changes in the BIOS firmware version, BIOS settings, and CPU microcode. If you want to keep
the same physical hardware, do not stop the instance using the Console or the API, SDKs, or
CLI. Instead, shut down the instance using the instance's OS. When you want to restart the
instance, use the Console or the API, SDKs, or CLI.
This behavior applies to Linux instances that use the following shapes:
l BM.Standard1.36
l BM.Standard.B1.44
l BM.Standard2.52
l BM.Standard.E2.64
Note
l STOP
l RESET
Terminating an Instance
You can permanently terminate (delete) instances that you no longer need. Any attached
VNICs and volumes are automatically detached when the instance terminates. Eventually, the
instance's public and private IP addresses are released and become available for other
instances.
By default, the instance's boot volume is preserved when you terminate the instance. You can
attach the boot volume to a different instance as a data volume, or use it to launch a new
instance. If you no longer need the boot volume, you can permanently delete it at the same
time that you terminate the instance.
Warning
For administrators: The policy in Let users launch Compute instances includes the ability to
terminate an instance (with or without an attached block volume).
If you're new to policies, see Getting Started with Policies and Common Policies. For
reference material about writing policies for instances, cloud networks, or other Core
Services API resources, see Details for the Core Services.
Warning
Except for Compute instances, all resources that support the Monitoring service emit metrics
by default. A Compute instance using a supported image emits metrics when it has the
required instance configuration and Oracle Cloud Agent software.
Supported Images
Compute instances with either Oracle-provided images or Oracle Linux 8.x (available through
the Marketplace) support the configuration setting to enable monitoring. When this setting is
enabled for an instance and the Oracle Cloud Agent software is installed on the instance, the
instance emits metrics.
Note
Prerequisites
l Service gateways or public IP addresses: The Compute instances must have either
service gateways or public IP addresses to send metrics to the Monitoring service.
l IAM policies: To create and update Compute instances, 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 more information, see Creating an Instance.
l Instance access: To connect to a Linux Compute instance, you must have an SSH key.
To connect to a Windows instance, you must have the instance password. For more
information, see Connecting to an Instance.
Note
While defining properties for the new instance, set the property that enables the instance for
monitoring. For instructions, see Using the Console or Using the API.
While defining properties for the new instance, set the property that enables the instance for
monitoring and do one of the following:
l In the Console: While defining properties for the new instance, provide a script to install
the Oracle Cloud Agent software onto the instance during the instance creation process.
l Complete the instance creation process and then manually install the Oracle Cloud
Agent software.
l When creating the service gateway, enable the service label called All <region>
Services in Oracle Services Network. It includes the Monitoring service.
l When setting up routing for the subnet that contains your instances, set up a route rule
with Target Type set to Service Gateway, and the Destination Service set to All
<region> Services in Oracle Services Network.
Query metrics to determine if Monitoring is receiving metrics emitted by the instance. For
instructions, see Using the Console or Using the API.
No Oracle Cloud Agent software exists on the instance Connect to Install the
(occurs with older images). the instance software.
and look for
the software.
The instance cannot access theMonitoring service because its Review the Set up a
VCN does not use the Internet. instance's IP service
address. If gateway.
it's not
public, then a
service
gateway is
needed.
Update the instance configuration to enable monitoring. For instructions, see Using the
Console or Using the API.
Linux
This section covers CentOS, Oracle Linux, and Ubuntu images.
cd ~
curl -O https://objectstorage.us-phoenix-
1.oraclecloud.com/p/VF8wKrvDVvoTs5MVkOa5Z33ox74eWqkaSldo9gKpnF0/n/imagegen/b/agents/o/oracle-
cloud-agent-0.0.19-22.el6.x86_64.rpm -v
cd ~
curl -O https://objectstorage.us-phoenix-
1.oraclecloud.com/p/gThzYC5DciU7Ltv4TspFtZ0iW3Rk0xzB2zOgE2ybrW8/n/imagegen/b/agents/o/oracle-
cloud-agent-0.0.19-22.el7.x86_64.rpm -v
cd ~
curl -O https://objectstorage.us-phoenix-1.oraclec
wr8HdivAAIVn9u0Ip8n2kGqAqao9N3Gqop6y-HOU/n/imagegen/b/agents/o/oracle-cloud-agent-0.0.19-
22.el8.x86_64.rpm -v
Note
4. Enter the relevant command to run the Oracle Cloud Agent software on the instance.
Windows
1. Enable monitoring on the instance.
2. Download the Oracle Cloud Agent software from the following URL.
https://objectstorage.us-phoenix-1.oraclecloud.com/p/xACZlZ-
LnvJOU2PacNHDcGTpuYf-iZDkTDtl2MHM-fE/n/imagegen/b/windows_instance_
agents/o/OracleCloudAgentSetup.msi
3. Connect to the instance.
4. Copy the downloaded Oracle Cloud Agent software to the instance.
5. As a user with administrative privileges, enter the relevant command to run the Oracle
Cloud Agent software on the instance.
msiexec /qb /i <instance-agent-filename>
If your instances do not have public IP addresses, set up a service gateway on the virtual
cloud network (VCN). The service gateway allows the instances to send metrics to the
Monitoring service without the traffic going over the internet. Here are special notes for
setting up the service gateway to access the Monitoring service:
l When creating the service gateway, enable the service label called All <region>
Services in Oracle Services Network. It includes the Monitoring service.
l When setting up routing for the subnet that contains your instances, set up a route rule
with Target Type set to Service Gateway, and the Destination Service set to All
<region> Services in Oracle Services Network.
If the installed software can access the internet, then no action is needed. The software
periodically checks for newer versions and automatically installs the latest version when
different from the current version.
If the installed software does not have access to the internet, then a manual update is
required. For example, a Compute instance that has no internet gateway or service gateway
cannot access the internet. In this situation, the software cannot complete its checks for
newer versions.
Example output:
IdentifyingNumber : {exampleuniqueidentifer}
Name : Oracle Cloud Agent
Vendor : Oracle Corporation
Version : 0.0.10.0
Caption : Oracle Cloud Agent
Linux versions
The Oracle Cloud Agent software is supported on the following Oracle-provided images for
Linux:
l CentOS 6.x
l CentOS 7.x
l Oracle Linux 6.x
l Oracle Linux 7.x
l Ubuntu 16.04
l Ubuntu 18.04
In addition, the Oracle Cloud Agent software is supported on the Oracle Linux 8.x image,
available through the Marketplace.
0.0.19 May 28, Fix updater failing to run on images that mount
2020 a filesystem with noexec flag set, to /tmp
Windows versions
Steps depend on the date of the image used to create the instance.
Note
1. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Instances. Choose a Compartment you have permission to work in, and then click
Create Instance.
2. On the Create Compute Instance page, select the latest version of a supported
image.
For more information about launching instances, see Creating an Instance.
3. Click Show Advanced Options.
4. On the Management tab, in the Oracle Cloud Agent section, select the Enable
monitoring check box.
5. Update other configuration as needed and then click Create.
The newly created, monitoring-enabled instance emits metrics to the Monitoring
service.
1. Open the navigation menu. Under Core Infrastructure, go to Compute and click
Instances. Choose a Compartment you have permission to work in, and then click
Create Instance.
2. On the Create Compute Instance page, select the legacy version of the supported
image.
For more information about launching instances, see Creating an Instance.
3. Click Show Advanced Options.
4. On the Management tab, do the following:
a. In the Initialization Script section, select Paste cloud-init script. Copy and
paste the script corresponding to the image used by the instance.
l CentOS 6.x, Oracle Linux 6.x
#!/bin/sh
curl -O https://objectstorage.us-phoenix-
1.oraclecloud.com/p/VF8wKrvDVvoTs5MVkOa5Z33ox74eWqkaSldo9gKpnF0/n/imagegen/b/agent
s/o/oracle-cloud-agent-0.0.19-22.el6.x86_64.rpm
yum install -y ~/orac
Note
#ps1_sysnative
cd \Users\opc\Desktop
Start-BitsTransfer -Source "https://objectstorage.us-phoenix-
1.oraclecloud.com/p/xACZlZ-LnvJOU2PacNHDcGTpuYf-iZDkTDtl2MHM-
fE/n/imagegen/b/windows_instance_agents/o/OracleCloudAgentSetup.msi" -Destination
"c:\Users\opc\Desktop\OracleCloudAgentSetup.msi"
msiexec /i "c:\Users\opc\Desktop\OracleCloudAgentSetup.msi" /quiet /L*V
"c:\Users\opc\Desktop\OracleCloudAgentSetup.log"
Note
b. In the Oracle Cloud Agent section, select the Enable monitoring check box.
5. Update other configuration as needed and then click Create.
The newly created, monitoring-enabled instance emits metrics to the Monitoring
service.
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.
Note
Use the LaunchInstance API operation, specifying the latest version of a supported image, and
include the following parameter setting.
{
"agentConfig":
{
"isMonitoringDisabled":false
}
}
1. Use the LaunchInstance API operation, specifying the legacy version of the supported
image, and include the following parameter setting.
{
"agentConfig":
{
"isMonitoringDisabled":false
}
}
2. Install the Oracle Cloud Agent software on the newly created instance. See Task 2:
Install the Oracle Cloud Agent software.
Compute Metrics
You can monitor the health, capacity, and performance of your Oracle Cloud Infrastructure
resources by using metrics, alarms, and notifications. For more information, see Monitoring
Overview and Notifications Overview.
There are multiple Monitoring service metric namespaces related to Compute resources:
This topic describes the metrics emitted by the metric namespace oci_computeagent (the
Oracle Cloud Agent software on Compute instances).
You can view these metrics for individual Compute instances, and for all the instances in an
instance pool.
This section gives an overall picture of the different types of metrics available for an instance
and its storage and network devices. See the following diagram and table for a summary.
oci_ Boot or By the Block Volume service. The metrics are See Block
blockstore block for an individual volume (either boot volume Volume
volume or block volume). Metrics.
OCID
oci_vcn VNIC By the Networking service. The metrics are See VNIC
OCID for an individual VNIC. Metrics.
Prerequisites
l IAM policies: To monitor resources, 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. The policy must give you access to the monitoring
services as well as the resources being monitored. 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 more information on user authorizations for monitoring, see the
Authentication and Authorization section for the related service: Monitoring or
Notifications.
l Metrics exist in Monitoring: The resources that you want to monitor must emit metrics
to the Monitoring service.
The Compute instance metrics help you measure activity level and throughput of Compute
instances. The metrics listed in the following table are available for any monitoring-enabled
Compute instance. You must enable monitoring on the instances to get these metrics.
The metrics in this namespace are aggregated across all the related resources on the
instance. For example, DiskBytesRead is aggregated across all the instance's attached
storage volumes, and NetworkBytesIn is aggregated across all the instance's attached
VNICs.
You also can use the Monitoring service to create custom queries.
AVAILABILITYDOMAIN
FAULTDOMAIN
IMAGEID
INSTANCEPOOLID
REGION
RESOURCEDISPLAYNAME
RESOURCEID
SHAPE
For instance
pools, the
value is
averaged
across all
instances in
the pool.
No Oracle Cloud Agent software exists on the instance Connect to Install the
(occurs with older images). the instance software.
and look for
the software.
For more information about monitoring metrics and using alarms, see Monitoring
Overview. For information about notifications for alarms, see Notifications Overview.
Click Metrics to see the volume's charts. For more information about the emitted
metrics, see Block Volume Metrics.
l For an attached VNIC: While viewing the instance's details, under Resources, click
Attached VNICs, and then click the VNIC that you're interested in. Click Metrics to
see the charts for the VNIC. For more information about the emitted metrics, see
Networking Metrics.
For more information about monitoring metrics and using alarms, see Monitoring Overview.
For information about notifications for alarms, see Notifications Overview.
For more information about monitoring metrics and using alarms, see Monitoring Overview.
For information about notifications for alarms, see Notifications Overview.
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.
This topic describes the metrics emitted by the metric namespace oci_compute_
infrastructure_health.
Resources: Compute instances.
The Compute infrastructure health metrics help you monitor the status and health of Compute
instances.
l Instance health (up/down) status: The instance_status metric lets you check
whether a VM or bare metal instance is available (up) or unavailable (down) when in the
running state.
l Bare metal infrastructure health status: The health_status metric helps you
monitor the health of the infrastructure for bare metal instances, including hardware
components such as the CPU and memory.
Based on the value of the metrics, you can proactively move affected instances to healthy
hardware and thereby minimize the impact on your applications.
To monitor resources, 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. The policy must give you access to the monitoring services as well as the resources
being monitored. 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 more information on user
authorizations for monitoring, see the Authentication and Authorization section for the related
service: Monitoring or Notifications.
The metrics listed in the following table are automatically available for your instances. The
instance_status metric is available for both VM and bare metal instances, and the health_
status metric is available only for bare metal instances. You do not need to enable
monitoring on the instance to get these metrics.
You also can use the Monitoring service to create custom queries.
FAULTC LASS
For troubleshooting suggestions and more information about these hardware issues, see
Compute Health Monitoring for Bare Metal Instances.
RESOURCEDISPLAYNAME
RESOURCEID
For more information about monitoring metrics and using alarms, see Monitoring Overview.
For information about notifications for alarms, see Notifications Overview.
For more information about monitoring metrics and using alarms, see Monitoring Overview.
For information about notifications for alarms, see Notifications Overview.
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.
Oracle Cloud Infrastructure provides a variety of instance configurations in both bare metal
and virtual machine (VM) shapes. Each shape varies on multiple dimensions including
memory, CPU cores, network bandwidth, and the option of local NVMe SSD storage found in
DenseIO shapes.
Oracle Cloud Infrastructure provides a service-level agreement (SLA) for NVMe performance.
Measuring performance is complex and open to variability.
An NVMe drive also has non-uniform drive performance over the period of drive usage. An
NVMe drive performs differently when tested brand new compared to when tested in a steady
state after some duration of usage. New drives have not incurred many write/erase cycles
and the inline garbage collection has not had a significant impact on IOPS performance. To
achieve the goal of reproducibility and reduced variability, our testing focuses on the steady
state duration of the NVMe drive’s operation.
Testing Methodology
Warning
Summary: To capture the IOPS measure, first provision a shape such as the BM.DenseIO2.52
shape, and then use the Gartner Cloud Harmony test suite to run tests on an instance running
the latest supported Oracle Linux 7 image for each NVMe drive target.
Instructions:
1. Launch an instance based on the latest supported Oracle Linux 7 image and select a
shape such as the BM.DenseIO2.52 shape. For instructions, see Creating an Instance.
2. Run the Gartner Cloud Harmony test suite tests on the instance for each NVMe drive
target. The following is an example of a command that will work for all shapes and
drives on the shape:
sudo ./run.sh `ls /dev/nvme[0-9]n1 | sed -e 's/\//\--target=\//'`
--nopurge –noprecondition --fio_direct=1 --fio_size=10g --test=iops
--skip_blocksize=512b --skip_blocksize=8k --skip_blocksize=16k
--skip_blocksize=32k --skip_blocksize=64k --skip_blocksize=128k
--skip_blocksize=1m
The SLA for NVMe drive performance is measured against 4k block sizes with 100% random
write workload on DenseIO shapes where the drive is in a steady state of operation.
Performance Benchmarks
The following table lists the minimum IOPS for the specified shape to meet the SLA, given the
testing methodology with 4k block sizes for 100% random write tests using the tests
described in the previous section.
VM.DenseIO1.4 200k
VM.DenseIO1.8 250k
VM.DenseIO1.16 400k
BM.DenseIO1.36 2.5MM
VM.DenseIO2.8 250k
VM.DenseIO2.16 400k
VM.DenseIO2.24 800k
BM.DenseIO2.52 3.0MM
Although the NVMe drives are capable of higher IOPS, Oracle Cloud Infrastructure currently
guarantees this minimum level of IOPS performance.
Health monitoring notifications are emailed to the tenant administrator within one business
day of the error occurring. This warning helps you to take action before any potential
hardware failure and redeploy your instances to healthy hardware to minimize the impact on
your applications.
You can also use the infrastructure health metrics available in the Monitoring service to create
alarms and notifications based on hardware issues.
Details: This error indicates that a processor or one or more cores have failed in your
instance. Your instance might be inaccessible or there might be fewer available cores than
expected.
Troubleshooting steps:
l If the instance is inaccessible, you must replace it using the steps in Moving a Compute
Instance to a New Host.
l If your instance is available, check for the expected number of cores:
o On Linux-based systems, run the following command:
nproc --all
Details: This error indicates that one or more failed DIMMs were detected in your instance
while the instance was being launched or rebooted. Any failed DIMMs have been disabled.
Troubleshooting steps: The total amount of memory in the instance will be lower than
expected. If this impacts your application, we recommend that you replace the instance using
the steps in Moving a Compute Instance to a New Host.
Details: This error indicates that one or more non-critical errors were detected on a DIMM in
your instance. The instance might have unexpectedly rebooted in the last 72 hours.
Troubleshooting steps:
l If the instance has unexpectedly rebooted in the last 72 hours, one or more DIMMs
might have been disabled. To check for the total amount of memory in the instance:
o On Linux-based systems, run the following command:
awk '$3=="kB"{$2=$2/1024**2;$3="GB";} 1' /proc/meminfo | column -t | grep MemTotal
If the total memory in the instance is lower than expected, then one or more DIMMs
have failed. If this impacts your application, we recommend that you replace the
instance using the steps in Moving a Compute Instance to a New Host.
l If the instance has not unexpectedly rebooted, it is at increased risk of doing so. During
the next reboot, one or more DIMMs might be disabled. We recommend that you
replace the instance using the steps in Moving a Compute Instance to a New Host.
Details: This error indicates that a device used to manage your instance might have failed.
You might not be able to use the Console, CLI, SDKs, or APIs to stop, start, or reboot your
instance. This functionality will still be available from within the instance using the standard
operating system commands. You also might not be able to create a console connection to
your instance. You will still be able to terminate your instance.
Troubleshooting steps: If this loss of control impacts your application, we recommend that
you replace the instance using the steps in Moving a Compute Instance to a New Host.
Details: This error indicates that one or more of the PCI devices in your instance have failed
or are not operating at peak performance.
Troubleshooting steps:
l If you cannot connect to the instance over the network, the NIC might have failed. Use
the Console or CLI to stop the instance and then start the instance. For steps, see
Stopping and Starting an Instance.
If you're still unable to connect to the instance over the network, you might be able to
connect to it using a console connection. Follow the steps in Connecting to the Serial
Console or Connecting to the VNC Console to establish a console connection and then
reboot the instance. If the instance remains inaccessible, you must replace it using the
steps in Moving a Compute Instance to a New Host.
l An NVMe device may have failed.
On Linux-based systems, run the command sudo lsblk to get a list of the attached
NVMe devices.
On Windows-based systems, open Disk Manager. Check the count of NVMe devices
against the expected number of devices in Compute Shapes.
If you determine that an NVMe device is missing from the list of devices for your
instance, we recommend that you replace the instance using the steps in Moving a
Compute Instance to a New Host.
For more information about this Microsoft benefit, see Microsoft License Mobility through
Software Assurance.
Eligibility Requirements
To enroll in Microsoft License Mobility through Software Assurance, you must be a Microsoft
Volume License customer with eligible server application products. The following are key
requirements:
l Windows Server operating systems, desktop client operating systems, and desktop
applications such as Microsoft Office are not eligible under License Mobility through
Software Assurance.
l Active Software Assurance coverage is required on eligible licenses migrated to Oracle
Cloud Infrastructure.
l All licenses that are used to run and access your licensed software require active
Software Assurance coverage. This includes server licenses, processor licenses, Client
Access Licenses (CALs), External Connector (EC) licenses, and server management
licenses. Your rights to run licensed software and manage instances on Oracle Cloud
Infrastructure expire with the expiration of the Software Assurance coverage on those
licenses.
l Eligible Volume Licensing programs include the Microsoft Enterprise Agreement,
Microsoft Enterprise Subscription Agreement, and Microsoft Open Value agreement,
where Software Assurance is included, and other Volume Licensing programs where
Software Assurance is an option, such as the Microsoft Open License agreement and the
Microsoft Select Plus agreement.
l You may move Microsoft licenses from on-premises or another cloud services provider
only after more than 90 days have passed since the last license move.
l Eligible Microsoft licenses on Oracle Cloud Infrastructure must be maintained for a
minimum period of 90 days in a specific Oracle Cloud Infrastructure region. After the
90-day period, you may move the licensed software to a shared host in another Oracle
Cloud Infrastructure region.
l Any Microsoft Server licenses permitted on Oracle Cloud Infrastructure must be eligible
according to the latest Microsoft Product Terms. It is your responsibility to verify that
the licenses you bring to Oracle Cloud Infrastructure are eligible according to the latest
Microsoft Product Terms.
All customers using License Mobility through Software Assurance must complete a license
verification process. Microsoft verifies that you have eligible licenses with active Software
You can deploy your application server software before completing the verification process,
but you must submit the license verification form within 10 days of deployment.
You are responsible for managing true ups and renewals as required under your Volume
Licensing agreement.
You must submit a new form each time that you deploy additional licenses, when you renew
your agreement, and when you deploy any previously unverified products.
1. Verify that you are a Microsoft Volume Licensing customer with eligible application
server licenses that are covered by active Software Assurance.
2. Download the license verification form:
a. Go to the Microsoft Product Licensing search page.
b. In the Document Type area, select License Verification.
c. Filter the results by language, region, and business sector. Note that the
verification form is not available in the WW (World Wide) region.
d. Download the LicenseMobilityVerif document.
3. Complete the license verification form. To specify Oracle as the Authorized Mobility
Partner, provide the following information:
l Authorized Mobility Partner Name: Oracle America, Inc.
l Authorized Mobility Partner Website URL: http://www.oracle.com/
l Authorized Mobility Partner Email Address: microsoftlm_us_
[email protected]
For instructions to complete the form, see the Microsoft License Mobility Verification
Guide (PDF).
For the latest Microsoft licensing requirements, refer to the Microsoft Product Terms.
If you can't find the answer to your question here, or you need more assistance running
Microsoft products on Oracle Cloud Infrastructure, contact Oracle Support.
General Questions
If you don't need to migrate your Windows OS licenses, you can use the Bring Your Own
Image process to migrate your Windows image to Oracle Cloud Infrastructure.
Is Windows Server 2019 available as a Bring Your Own Image (BYOI) image?
Yes, you can import your own Windows Server 2019 image for virtual machines only. For
source image requirements and steps to import an image, see Importing Custom Windows
Images.
What VM and bare metal options are available for Windows Server operating
systems?
The following table shows support for Microsoft Windows Server operating systems on Oracle
Cloud Infrastructure.
Bring your own virtual machine image. You can Not Supported Volume
import your own custom virtual machine Windows supported license issued
Server OS image. by Oracle
Cloud
Infrastructure
Bring your own Windows Server ISO image. Not Not Customer-
supported supported owned license
Bring your own hypervisor. You can use a Supported Not Volume
Windows Server 2016 or Windows Server 2019 supported license issued
Datacenter hypervisor host provided by Oracle by Oracle
Cloud Infrastructure and import your own VM Cloud
images. Infrastructure
Does Oracle Cloud Infrastructure support Bring Your Own Image (BYOI) for
Windows Server?
Yes, you are permitted to import your own generalized custom image of Windows Server.
When you create an instance with an imported image on a VM or a shared bare metal
machine, Oracle Cloud Infrastructure licenses the instance. For more information about
imported images, see Creating Windows Custom Images.
If you want to use your own license, BYOI is supported only for bare metal machines on a
dedicated host.
Billing for the Windows Server license is based on per-OCPU, per-second usage. Billing starts
when an instance is in the "running" state and ends when you terminate (delete) the instance.
When an instance is stopped, billing for the Windows Server license depends on the shape that
was used to create the instance. Billing pauses for instances that use a Standard shape. Billing
continues for instances that use a Dense I/O shape, GPU shape, or HPC shape. Depending on
the shape, you might also be billed for the underlying Compute instance when the instance is
stopped.
How does Windows Server get updated with the latest patches?
You must update your VCN's security list to enable egress traffic for port 80 (HTTP) and port
443 (HTTPS) to install patches from Microsoft. Oracle Cloud Infrastructure enables automatic
updates for Microsoft Windows Server and uses the default settings for applying Windows
Server patches.
l Create a custom image: Creates a custom image that you can use to launch other
instances. Instances that you launch from your image include the customizations,
configuration, and software installed when you created the image.
l Clone a boot volume: Makes a copy of an existing boot volume without needing to go
through the backup and restore process. A boot volume clone is a point-in-time direct
disk-to-disk deep copy of the source boot volume, so all the data that is in the source
boot volume when the clone is created is copied to the boot volume clone.
l Back up a block volume: Makes a point-in-time backup of data on a block volume. You
can restore a backup to a new volume either immediately after a backup or at a later
time that you choose.
l Back up a boot volume: Makes a backup of a boot volume. Boot volume backup
capabilities are the same as block volume backup capabilities and are in-region only.
Windows boot volume backups cannot be copied across regions.
What is BYOL?
BYOL stands for "bring your own license." BYOL lets you use software licenses that you
already own to deploy software on Oracle Cloud Infrastructure, without any additional
licensing fees. This process uses the License Mobility through Microsoft Software Assurance
benefit provided by Microsoft. You must have active Software Assurance with Microsoft to
bring your licenses to Oracle Cloud Infrastructure.
With License Mobility through Software Assurance, you can deploy eligible application servers
on bare metal hosts or virtual shared hardware in Oracle Cloud Infrastructure. An example of
an application eligible for License Mobility through Software Assurance is Microsoft SQL.
Windows Server operating systems are not eligible.
You may move Microsoft licenses from on-premises or another Authorized Mobility Partner
only after more than 90 days have passed since the last license move.
For more information about this Microsoft benefit, see Microsoft License Mobility through
Software Assurance. For steps to move your Microsoft licenses to Oracle Cloud Infrastructure,
see Moving Microsoft Licenses to Oracle Cloud Infrastructure: Microsoft License Mobility.
Can I bring my own license for Microsoft Windows Server to Oracle Cloud
Infrastructure?
Yes. You can bring your own license (BYOL) for Microsoft Windows Server, subject to the
Microsoft Product Terms. You are responsible for managing your own licenses to maintain
compliance with Microsoft licensing terms.
The following table shows the BYOL requirements for Microsoft licenses on Oracle Cloud
Infrastructure.
Windows BYOL on a bare metal dedicated host is only supported when Not
Server using a KVM hypervisor if the licenses were purchased before supported.
October 1, 2019. BYOL is not supported for Microsoft Windows
Shared
Server using Oracle-provided images or when importing your
hosts must
own Microsoft Windows Server image. Any licenses that were
use Oracle-
purchased or upgraded on or after October 1, 2019 for use on a
provided
dedicated host are not permitted on Oracle Cloud
images that
Infrastructure.
include the
Microsoft
license.
Subject to You must have License Mobility through Software Assurance. You must
the have
Microsoft License
Product Mobility
Terms through
Software
Assurance
and use an
Oracle-
provided
image.
Application licenses require License Mobility through Software Assurance when running on
Oracle Cloud Infrastructure VM instances.
Questions about your licensing rights should be directed to Microsoft or your Microsoft
reseller.
Can I use virtual machines and bring my own license for Microsoft Windows
Server to Oracle Cloud Infrastructure?
You cannot migrate your Windows Server OS licenses when using Oracle Cloud Infrastructure
virtual machines.
However, you can bring your own hypervisor (KVM) to run a Windows Server VM with your
own Windows Server OS license.
l You can use VMs with their own license only if you use bring your own hypervisor on a
dedicated bare metal host.
l BYOL of Microsoft Windows Server is not supported for VMs running on a shared host.
Oracle Cloud Infrastructure-provided VMs offer Windows Server.
o You can use a bare metal instance under bring your own hypervisor.
o You must install and manage a hypervisor (KVM or Hyper-V) and launch your own
VMs. This will ensure isolation, because all Oracle VMs are running on a dedicated
bare metal server. The VMs can run Windows Server if they are licensed through
MSDN (development use only).
l BYOL on a dedicated host (KVM hypervisor only) is permitted for Microsoft Windows
Server only if the licenses were purchased before October 1, 2019. Any licenses that
were purchased or upgraded on or after October 1, 2019 for use on a dedicated host are
not permitted on Oracle Cloud Infrastructure.
according to the latest Microsoft Product Terms. It is your responsibility to verify that the
licenses you bring to Oracle Cloud Infrastructure are eligible according to the latest Microsoft
Product Terms. All products that are currently eligible for License Mobility and covered by
Software Assurance are eligible for BYOL.
l When you move your Microsoft SQL license using the license mobility process, the
Microsoft Windows Server license is not included. Microsoft Windows Server licenses
are not permitted to be moved under License Mobility. Windows Server operating
systems must use the license issued by Oracle Cloud Infrastructure.
l Perpetual licenses can be moved from on-premises or other cloud providers only after
more than 90 days have passed since the last license move.
l End-of-support versions are not supported on shared host virtual machines on Oracle
Cloud Infrastructure.
Follow the license mobility process to move your SQL Server license to Oracle Cloud
Infrastructure.
You can use virtual machines with your own MSDN license only if you bring your own
hypervisor (KVM). You cannot use your MSDN license when using virtual machines on Oracle
Cloud Infrastructure.
RDS Client Access Licenses (CALs) are required for each user or device using Remote
Desktop.
Can I bring my own RDS CALs if I want more than two users to access my
Windows Server instance?
Yes, you can use your Remote Desktop Services (RDS) Client Access Licenses (CALs) on
Oracle Cloud Infrastructure if you use the Oracle Cloud Infrastructure bare metal offering. In
addition, you can use virtual machines with their own MSDN license if you bring your own
hypervisor (KVM).
You can use your RDS CAL licenses on Oracle Cloud Infrastructure virtual machines only if you
have active Software Assurance coverage and move your CALs using the license mobility
process.
System Center client Management Licenses (client MLs) are not eligible for license mobility
and cannot be moved to Oracle Cloud Infrastructure.
Are there user data capabilities when launching Windows Server images?
Yes, Oracle-provided Windows images include cloudbase-init installed by default. You can use
cloudbase-init to run PowerShell scripts, batch scripts, or other user data content on instance
launch. Cloudbase-init is the equivalent of cloud-init on Linux-based images.
Can I use Windows Server 2008 R2 even though it's past the end-of-support
date?
Windows Server 2008 R2 reached the end of its support lifecycle on January 14, 2020.
Although you can continue to import your own Windows 2008 R2 images and run your existing
instances, you are at a higher risk of security issues, incompatibility, or failures. Oracle does
not provide any operating system support for end-of-support operating systems.
Oracle Cloud Infrastructure does not provide platform images after the end-of-support date.
However, you can import your own image and launch it on a shared host VM.
For VMs on shared infrastructure, you must have an enterprise agreement in place with
Microsoft. With that agreement in place, you can purchase ESUs per virtual core matching the
number of OCPUs per VM instance, with a minimum requirement of 16 virtual core licenses
per VM instance.
For bare metal machines, you must have an enterprise agreement in place with Microsoft.
With that agreement in place, you can purchase ESUs per physical core of the dedicated bare
metal host.
You are fully responsible for purchasing the correct number of ESUs for your instances. Oracle
Cloud Infrastructure does not keep track of whether you have enough ESUs.
The following platform images distributed by Oracle Cloud Infrastructure are configured so
that the iscsid service restarts automatically:
Instances created from earlier versions of CentOS 7.x and Oracle Linux platform images, or
any versions of Oracle Cloud Infrastructure CentOS 6.x and Ubuntu platform images, do not
have this configuration. You should update these existing instances and custom images
created from these images so that the iscsid service restarts automatically. You should also
check this configuration on your imported paravirtualized custom images and any instances
launched from these images and update the configuration as needed.
This topic describes how to update the iscsid service on an instance so that it will restart
automatically.
Note
Oracle Linux 7
Run the following command to update the iscsid service on your Oracle 7 Linux instances:
sudo yum update -y iscsi-initiator-utils
After running this command, the version of the iscsid service should be 6.2.0.874 or newer.
This update does not require a system reboot and will not make any changes to your instances
beyond configuring iscsid to restart automatically.
Oracle Linux 6
Run the following command to update the iscsid service on your Oracle 6 Linux instances:
sudo yum update -y iscsi-initiator-utils
After running this command, the version of the iscsid service should be 6.2.0.873 or newer.
This update does not require a system reboot and will not make any changes to your instances
beyond configuring iscsid to restart automatically.
CentOS 7.x
Important
On your CentOS 7 instances run the following command to create an override file:
sudo systemctl edit iscsid.service
Run the following commands to reload systemd and restart the iscsid service:
sudo systemctl daemon-reload
sudo systemctl restart iscsid
CentOS 6.x
On your CentOS 6 instances run the following command to install the monit package:
sudo yum install monit
Ubuntu 18
Important
On your Ubuntu 18 instances run the following command to create an override file:
sudo systemctl edit iscsid.service
Run the following commands to reload systemd and restart the iscsid service:
sudo systemctl daemon-reload
sudo systemctl restart iscsid
Ubuntu 16
Important
On your Ubuntu 16 instances run the following command to create an override file:
sudo systemctl edit iscsid.service
Run the following commands to reload systemd and restart the iscsid service:
sudo systemctl daemon-reload
sudo systemctl restart iscsid
Ubuntu 14
On your Ubuntu 14 instances run the following command to install the monit package:
sudo apt-get install monit
Warning
1. Run the following command to confirm that the iscsid service is running:
ps -ef | grep iscsid
3. Wait 60 seconds and then run the following command to verify that the iscsid service
has restarted:
ps -ef | grep iscsid
Container Engine for Kubernetes uses Kubernetes - the open-source system for automating
deployment, scaling, and management of containerized applications across clusters of hosts.
Kubernetes groups the containers that make up an application into logical units (called pods)
for easy management and discovery. Container Engine for Kubernetes uses versions of
Kubernetes certified as conformant by the Cloud Native Computing Foundation (CNCF).
Container Engine for Kubernetes is itself ISO-compliant (ISO-IEC 27001, 27017, 27018).
You can access Container Engine for Kubernetes to define and create Kubernetes clusters
using the Console and the REST API. You can access the clusters you create using the
Kubernetes command line (kubectl), the Kubernetes Dashboard, and the Kubernetes API.
Container Engine for Kubernetes is integrated with Oracle Cloud Infrastructure Identity and
Access Management (IAM), which provides easy authentication with native Oracle Cloud
Infrastructure identity functionality.
For an introductory tutorial, see Creating a Cluster with Oracle Cloud Infrastructure Container
Engine for Kubernetes.
Note
For general information about using the API, see REST APIs.
See Container Engine for Kubernetes for details about Container Engine for Kubernetes
resources that emit events.
Resource Identifiers
Most types of Oracle Cloud Infrastructure resources have a unique, Oracle-assigned identifier
called an Oracle Cloud ID (OCID). For information about the OCID format and other ways to
identify your resources, see Resource Identifiers.
An administrator in your organization needs to set up groups, compartments, and policies that
control which users can access which services, which resources, and the type of access. For
example, the policies control who can create new users, create and manage the cloud
network, launch instances, create buckets, download objects, etc. For more information, see
Getting Started with Policies. For specific details about writing policies for each of the
different services, see Policy Reference.
If you’re a regular user (not an administrator) who needs to use the Oracle Cloud
Infrastructure resources that your company owns, contact your administrator to set up a user
ID for you. The administrator can confirm which compartment or compartments you should be
using.
Note that to perform certain operations on clusters created by Container Engine for
Kubernetes, you might require additional permissions granted via a Kubernetes RBAC role or
clusterrole. See About Access Control and Container Engine for Kubernetes.
For more details about policies for Container Engine for Kubernetes, see:
l one or more master nodes (for high availability, typically there will be a number of
master nodes)
l one or more worker nodes (sometimes known as minions)
A Kubernetes cluster can be organized into namespaces, to divide the cluster's resources
between multiple users. Initially, a cluster has the following namespaces:
Kubernetes Processes
The master nodes in a cluster run a number of processes:
l kube-apiserver to support API operations via the Kubernetes command line tool
(kubectl) and the REST API, and includes admissions controllers required for advanced
Kubernetes operations
l kube-controller-manager to manage different Kubernetes components (for example,
replication controller, endpoints controller, namespace controller, and serviceaccounts
controller)
l kube-scheduler to control where in the cluster to run jobs
l etcd to store the cluster's configuration data
The Kubernetes processes running on the master nodes are collectively referred to as the
Kubernetes Control Plane. Together, the Control Plane processes monitor and record the state
of the cluster and distribute requested operations between the nodes in the cluster.
Pods
Where an application running on a worker node comprises multiple containers, Kubernetes
groups the containers into a single logical unit called a pod for easy management and
discovery. The containers in the pod share the same networking namespace and the same
storage space, and can be managed as a single object by the Kubernetes Control Plane. A
number of pods providing the same functionality can be grouped into a single logical set
known as a service.
Node Pools
A node pool is a subset of machines within a cluster that all have the same configuration.
Node pools enable you to create pools of machines within a cluster that have different
configurations. For example, you might create one pool of nodes in a cluster as virtual
machines, and another pool of nodes as bare metal machines. A cluster must have a minimum
of one node pool, but a node pool need not contain any worker nodes.
Admission Controllers
A Kubernetes admission controller intercepts authenticated and authorized requests to the
Kubernetes API server before admitting an object (such as a pod) to the cluster. An admission
controller can validate an object, or modify it, or both. Many advanced features in Kubernetes
require an enabled admission controller. For more information, see the Kubernetes
documentation.
The Kubernetes version you select when you create a cluster using Container Engine for
Kubernetes determines the admission controllers supported by that cluster. To find out the
supported admission controllers, the order in which they run in the Kubernetes API server,
and the Kubernetes versions in which they are supported, see Supported Admission
Controllers.
l You must have access to an Oracle Cloud Infrastructure tenancy. The tenancy must be
subscribed to one or more of the regions in which Container Engine for Kubernetes is
available (see Availability by Region).
l Your tenancy must have sufficient quota on different types of resource (see Service
Limits). More specifically:
o Compute instance quota: To create a Kubernetes cluster, at least one compute
instance (node) must be available in the tenancy. However, you'll probably want
more than this minimum. For example, to create a highly available cluster in a
region with three availability domains (ADs), at least three compute instances
must be available (one in each availability domain).
o Block volume quota: If you intend to create Kubernetes persistent volumes,
sufficient block volume quota must be available in each availability domain to
meet the persistent volume claim. Persistent volume claims must request a
minimum of 50 gigabytes. See Creating a Persistent Volume Claim.
o Load balancer quota: If you intend to create a load balancer to distribute traffic
between the nodes running a service in a Kubernetes cluster, sufficient load
balancer quota must be available in the region. See Creating Load Balancers to
Distribute Traffic Between Cluster Nodes.
l Within your tenancy, there must already be a compartment to contain the necessary
network resources (such as a VCN, subnets, internet gateway, route table, security
lists). If such a compartment does not exist already, you will have to create it. Note that
the network resources can reside in the root compartment. However, if you expect
multiple teams to create clusters, best practice is to create a separate compartment for
each team.
l Within the compartment, network resources (such as a VCN, subnets, internet gateway,
route table, security lists) must be appropriately configured in each region in which you
want to create and deploy clusters. For example, to create a highly available cluster in a
region with three availability domains, the VCN must include:
Availability by Region
Container Engine for Kubernetes is available in the Oracle Cloud Infrastructure regions listed
at Regions and Availability Domains. Refer to that topic to see region identifiers, region keys,
and availability domain names.
In some cases, you might have to use the shortened versions of availability domain names
shown below. For example, when defining a persistent volume claim (PVC), to request
storage in a particular availability domain by specifying the value of the failure-
domain.beta.kubernetes.io/zone Kubernetes label (see Creating a Persistent Volume
Claim).
l Within the tenancy, there must already be a compartment to contain the necessary
network resources (such as a VCN, subnets, internet gateway, route table, security
lists). If such a compartment does not exist already, you will have to create it. Note that
the network resources can reside in the root compartment. However, if you expect
multiple teams to create clusters, best practice is to create a separate compartment for
each team.
l Within the compartment, network resources (such as a VCN, subnets, internet gateway,
route table, security lists) must be appropriately configured in each region in which you
want to create and deploy clusters. When creating a new cluster, you can have
Container Engine for Kubernetes automatically create and configure new network
resources for a new 'quick cluster'. Alternatively, you can explicitly specify the existing
network resources to use for a 'custom cluster'. If you specify existing network
resources, you or somebody else must have already configured those resources
appropriately, as described in this topic.
This topic describes the necessary configuration for each network resource. To see details of a
typical configuration, see Example Network Resource Configurations.
For an introductory tutorial, see Creating a Cluster with Oracle Cloud Infrastructure Container
Engine for Kubernetes.
VCN Configuration
The VCN in which you want to create and deploy clusters must be configured as follows:
l The VCN must have a CIDR block defined that is large enough for the number of subnets
you specify for the clusters you create. For example, to create a highly available cluster
in a region with three availability domains will typically require two regional subnets
(recommended) or five AD-specific subnets to support the necessary number of worker
nodes and load balancers. However, you can create clusters with fewer subnets. A /16
CIDR block would be large enough for almost all use cases (10.0.0.0/16 for example).
The CIDR block you specify for the VCN must not overlap with the CIDR block you
specify for pods and for the Kubernetes services (see CIDR Blocks and Container Engine
for Kubernetes).
l The VCN must have an appropriate number of subnets defined. For example, to create a
highly available cluster in a region with three availability domains, the VCN must
include:
o For worker nodes: a regional subnet (recommended), or three AD-specific
subnets (one in each of the availability domains).
o For load balancers: optionally (but usually) an additional regional subnet
(recommended), or an additional two AD-specific subnets (each in a different
availability domain).
However, you can create clusters with fewer worker nodes, and fewer or no load
balancers, and therefore require fewer subnets. Best practice is to use regional subnets
to make failover across availability domains simpler to implement. See Subnet
Configuration.
l The VCN must have security lists defined for worker node subnets and load balancer
subnets (if specified). See Security List Configuration.
In addition:
If you intend to deploy worker nodes in public subnets, and you expect deployed applications
to require the worker nodes to initiate connections to the internet, the VCN must have an
internet gateway. The internet gateway must be specified as the target for the destination
CIDR block 0.0.0.0/0 in a route rule in a worker node route table.
NAT Gateway Configuration
If you intend to deploy worker nodes in private subnets, and you expect deployed applications
to require the worker nodes to initiate connections to the internet, the VCN must have a NAT
gateway. The NAT gateway must be specified as the target for the destination CIDR block
0.0.0.0/0 in a route rule in a worker node route table.
If you expect applications deployed on a cluster to pull images from Oracle Cloud
Infrastructure Registry (or to use other Oracle Cloud Infrastructure resources) and you want
to protect data from the public internet, you can set up a service gateway. Setting up a
service gateway enables worker nodes to access other resources in the same region without
exposing data to the public internet.
When setting up the service gateway, create it in the same VCN and compartment as the
worker nodes, and select the All <region> Services in Oracle Services Network option.
Having created the service gateway, it must be specified as the target for All <region>
Services in Oracle Services Network in a route rule in the worker node route table.
Note that if you expect deployed applications to require access to public endpoints or services
not supported by a service gateway (for example, to download updates or patches), configure
additional network resources (such as a NAT gateway) to access the internet.
See Access to Oracle Services: Service Gateway and Example Network Resource
Configurations.
If you intend to deploy worker nodes in public subnets, and you expect deployed applications
to require the worker nodes to initiate connections to the internet, create an internet gateway.
Then create a worker node route table with a route rule that specifies the internet gateway as
the target for the destination CIDR block 0.0.0.0/0.
If you intend to deploy worker nodes in private subnets, and you expect deployed applications
to require the worker nodes to initiate connections to the internet, create a NAT gateway.
Then create a worker node route table with a route rule that specifies the NAT gateway as the
target for the destination CIDR block 0.0.0.0/0.
If you expect applications deployed on a cluster to pull images from Oracle Cloud
Infrastructure Registry (or to use other Oracle Cloud Infrastructure resources) and you don't
want to expose the data to the public internet, create a service gateway. Then create a worker
node route table with a route rule that specifies the service gateway as the target for All
<region> Services in Oracle Services Network.
Note that to avoid the possibility of asymmetric routing, a route table for a public subnet
cannot contain both a route rule that targets an internet gateway as well as a route rule that
targets a service gateway (for more information, see Issues with access from Oracle services
through a service gateway to your public instances).
See Internet Gateway, NAT Gateway, Access to Oracle Services: Service Gateway, and
Example Network Resource Configurations.
The VCN in which you want to create and deploy clusters must have DHCP Options configured.
The default value for DNS Type of Internet and VCN Resolver is acceptable.
The VCN in which you want to create and deploy clusters must have security lists defined for
worker node subnets and load balancer subnets (if specified). The security lists for worker
node subnets and load balancer subnets must be different. The security list for load balancer
subnets must be unique and for their exclusive use.
Worker nodes are created with public or private IP addresses, according to whether you
specify public or private subnets when defining the node pools in a cluster. Container Engine
for Kubernetes must be able to access worker nodes.
When configuring a security list for public worker node subnets, the security list must have:
l Stateless ingress and egress rules that allow all traffic between different worker node
subnets. (Usually necessary to enable pods on one worker node to communicate with
pods on other worker nodes. Only in the rare case where no inter-pod communication is
expected, is this not required.)
l Stateless ingress and egress rules that allow all traffic between worker node subnets
and load balancer subnets (if specified).
l Stateful egress rules that allow traffic between worker node subnets and Container
Engine for Kubernetes.
Optionally, you can include ingress rules for public worker node subnets to:
l Explicitly allow SSH access to worker nodes on port 22 (see Connecting to Worker
Nodes in Public Subnets Using SSH).
l Allow inbound traffic to the worker nodes on the default NodePort range of 30000 to
32767 (see the Kubernetes documentation).
Optionally, you can include an egress rule that allows all outbound traffic to the internet.
When configuring a security list for private worker node subnets, the security list must have:
l Stateless ingress and egress rules that allow all traffic between the different worker
node subnets. (Usually necessary to enable pods on one worker node to communicate
with pods on other worker nodes. Only in the rare case where no inter-pod
communication is expected, is this not required.)
l Stateless ingress and egress rules that allow all traffic between worker node subnets
and load balancer subnets.
l Stateful egress rules that allow traffic between worker node subnets and Container
Engine for Kubernetes.
Optionally, you can include ingress rules for private worker node subnets to:
l Explicitly allow SSH access to worker nodes on port 22 from within the VCN CIDR block
(see Connecting to Worker Nodes in Private Subnets Using SSH).
l Allow inbound traffic to the worker nodes on the default NodePort range of 30000 to
32767 from within the VCN CIDR block (see the Kubernetes documentation).
Optionally, you can include an egress rule that allows all outbound traffic to the internet.
Subnet Configuration
The characteristics of the cluster you want to create, and the number of availability domains
in the region in which you want to deploy the cluster, will determine the number of subnets to
configure. For example, to create a highly available cluster in a region with three availability
domains will require:
l For worker nodes: a regional subnet (recommended), or three AD-specific subnets (one
in each of the availability domains).
l For load balancers: optionally (but usually) an additional regional subnet
(recommended), or an additional two AD-specific subnets (each in a different
availability domain).
Best practice is to use regional subnets to make failover across availability domains simpler
to implement.
The VCN in which you want to create and deploy clusters must have at least one subnet
defined in which to deploy worker nodes. Worker node subnets can be either public, or private
for additional security (as specified by the Subnet access property). The number of worker
node subnets to create depends on the region in which you are creating the cluster:
l If you are creating a cluster in a region with multiple availability domains, you can
define a single regional subnet (recommended), or multiple AD-specific subnets (one in
each of the availability domains).
l If you are creating a cluster in a region with a single availability domain, you can define
a single regional subnet (recommended), or a single AD-specific subnet.
You have the option to define and use load balancers in clusters you create. If you want to
define and use load balancers, the VCN in which you want to create and deploy clusters must
have at least one subnet defined to host the load balancers. Load balancer subnets can be
public or private (as specified by the Subnet access property). However, load balancers are
optional, so you might not define load balancer subnets at all. The number of load balancer
subnets to define depends on the region in which you are creating the cluster:
l If you are creating a cluster in a region with three availability domains, you can define:
o zero or one load balancer regional subnet (recommended)
o zero or two load balancer AD-specific subnets. If you define two load balancer
AD-specific subnets, they must be in different availability domains.
l If you are creating a cluster in a region with a single availability domain, you can define
zero or one load balancer subnet:
o zero or one load balancer regional subnet (recommended)
o zero or one load balancer AD-specific subnet.
In addition, all subnets must have the following properties set as shown:
l Route Table: The name of a route table, if one has been created, that has a route rule
specifying an internet gateway (for public worker node subnets) or NAT gateway (for
private worker node subnets) as the target for the destination CIDR block 0.0.0.0/0,
and/or a route rule specifying a service gateway as the target for All <region>
Services in Oracle Services Network.
l DHCP options: Default.
The CIDR blocks you specify for worker node and load balancer subnets must not overlap with
CIDR blocks you specify for pods running in the cluster (see CIDR Blocks and Container Engine
for Kubernetes).
Worker node subnets must have different security lists to load balancer subnets.
l Within the tenancy, there must already be a compartment to contain the necessary
network resources (such as a VCN, subnets, internet gateway, route table, security
lists). If such a compartment does not exist already, you will have to create it. Note that
the network resources can reside in the root compartment. However, if you expect
multiple teams to create clusters, best practice is to create a separate compartment for
each team.
l Within the compartment, network resources (such as a VCN, subnets, internet gateway,
route table, security lists) must be appropriately configured in each region in which you
want to create and deploy clusters. When creating a new cluster, you can have
Container Engine for Kubernetes automatically create and configure new network
resources for a new 'quick cluster'. Alternatively, you can explicitly specify the existing
network resources to use for a 'custom cluster'. If you specify existing network
resources, you or somebody else must have already configured those resources
appropriately. See Network Resource Configuration for Cluster Creation and
Deployment.
This topic gives examples of how you might configure network resources for highly available
'custom cluster' creation and deployment in a region with three availability domains:
l for public clusters, where you want worker nodes hosted in public AD-specific subnets
that can be accessed directly from the internet (see Example 1: Example Network
Resource Configuration for a Highly Available Public Cluster in a Region with Three
Availability Domains, Using AD-Specific Subnets)
l for private clusters, where you want worker nodes hosted in private AD-specific subnets
that can only be accessed from within the VCN (see Example 2: Example Network
Resource Configuration for a Highly Available Private Cluster in a Region with Three
Availability Domains, Using AD-Specific Subnets)
l for public clusters, where you want worker nodes hosted in a public regional subnet that
can be accessed directly from the internet (see Example 3: Example Network Resource
Configuration for a Highly Available Public Cluster in a Region with Three Availability
Domains, Using a Regional Subnet)
Note that all the examples in this topic include a service gateway to enable worker nodes to
access other Oracle Cloud Infrastructure resources in the same region (such as Oracle Cloud
Infrastructure Registry) without exposing data to the public internet. However, you might be
expecting applications deployed on the cluster to require access to public endpoints or
services not supported by a service gateway. For example, to download updates or patches. If
so, configure additional network resources (such as a NAT gateway) to access the internet.
For an introductory tutorial, see Creating a Cluster with Oracle Cloud Infrastructure Container
Engine for Kubernetes.
This example assumes you want worker nodes hosted in three public AD-specific subnets that
can be accessed directly from the internet.
Resource Example
l Name: acme-dev-vcn
l CIDR Block: 10.0.0.0/16
l DNS Resolution: Selected
Resource Example
Route Table Two route tables created manually, named, and defined as follows:
Note that to avoid the possibility of asymmetric routing, a route table for a
public subnet cannot contain both a route rule that targets an internet
gateway as well as a route rule that targets a service gateway (for more
information, see Issues with access from Oracle services through a service
gateway to your public instances).
Resource Example
Security Lists Two created (in addition to the default security list) manually, named, and
defined as follows:
For details of the ingress rules and egress rules defined for the workers
security list and the loadbalancers security list, see Example Security List
Configurations for a Highly Available Public Cluster Using AD-Specific
Subnets.
Resource Example
Subnets Three worker node AD-specific subnets created manually, named, and
defined as follows:
Resource Example
EXAMPLE S ECURITY LIST CONFIGURATIONS FOR A HIGHLY AVAILABLE PUBLIC CLUSTER USING AD-
S PECIFIC S UBNETS
In the example VCN, two security lists have been created (in addition to the default security
list) to control access to and from the public worker node AD-specific subnets and the load
balancer AD-specific subnets. The two security lists are named 'workers' and 'loadbalancers'
respectively.
Note that two sets of alternative ingress and egress rules are given for the 'loadbalancers'
security list, showing how to allow either unrestricted access to/from the cluster, and how to
restrict access to/from a specific CIDR range.
Example Ingress Rules in the 'workers' Security List for Public Worker Node AD-
Specific Subnets:
1 State: 10.0.10.0/24 Protocol: n/a Allows: All traffic for all ports
Stateless All
Description: This optional rule enables
Src. Src. Port intra-VCN traffic. Although optional, this
Type: Range: rule is usually necessary to enable pods
CIDR n/a on one worker node to communicate
with pods on other worker nodes. Only
Dest.
in the rare case where no inter-pod
Port
communication is expected, is this rule
Range:
not required.
n/a
2 State: 10.0.11.0/24 Protocol: n/a Allows: All traffic for all ports
Stateless All
Description: This optional rule enables
Src. Src. Port intra-VCN traffic. Although optional, this
Type: Range: rule is usually necessary to enable pods
CIDR n/a on one worker node to communicate
with pods on other worker nodes. In the
Dest.
rare case where no inter-pod
Port
communication is expected, this rule is
Range:
not required.
n/a
3 State: 10.0.12.0/24 Protocol: n/a Allows: All traffic for all ports
Stateless All
Description: This optional rule enables
Src. Src. Port intra-VCN traffic. Although optional, this
Type: Range: rule is usually necessary to enable pods
CIDR n/a on one worker node to communicate
with pods on other worker nodes. In the
Dest.
rare case where no inter-pod
Port
communication is expected, this rule is
Range:
not required.
n/a
5 State: 0.0.0.0/0 Protocol: n/a Allows: TCP traffic for ports: 22 SSH
Stateful TCP Remote Login Protocol
Dest.
Port
Range:
22
6 State: 0.0.0.0/0 Protocol: n/a Allows: TCP traffic for ports: 30000 -
Stateful TCP 32767
Example Egress Rules in the 'workers' Security List for Public Worker Node AD-
Specific Subnets:
Consider these egress rules as a minimum requirement. If applications deployed on worker
nodes need to communicate with destinations outside of the Oracle Service Network, add
additional egress rules. For example, if applications use Helm charts from the Helm stable
repository, or Docker images from docker.io.
1 State: 10.0.10.0/24 Protocol: n/a Allows: All traffic for all ports
Stateless All
Description: This optional rule enables
Dest. Src. Port intra-VCN traffic. Although optional, this
Type: Range: rule is usually necessary to enable pods
CIDR n/a on one worker node to communicate
with pods on other worker nodes. Only
Dest.
in the rare case where no inter-pod
Port
communication is expected, is this rule
Range:
not required.
n/a
2 State: 10.0.11.0/24 Protocol: n/a Allows: All traffic for all ports
Stateless All
Description: This optional rule enables
Dest. Src. Port intra-VCN traffic. Although optional, this
Type: Range: rule is usually necessary to enable pods
CIDR n/a on one worker node to communicate
with pods on other worker nodes. Only
Dest.
in the rare case where no inter-pod
Port
communication is expected, is this rule
Range:
not required.
n/a
3 State: 10.0.12.0/24 Protocol: n/a Allows: All traffic for all ports
Stateless All
Description: This optional rule enables
Dest. Src. Port intra-VCN traffic. Although optional, this
Type: Range: rule is usually necessary to enable pods
CIDR n/a on one worker node to communicate
with pods on other worker nodes. Only
Dest.
in the rare case where no inter-pod
Port
communication is expected, is this rule
Range:
not required.
n/a
4 State: All <region> Protocol: All Allows: ICMP traffic for all ports.
Stateful Services in ICMP
Description: This rule enables
Oracle
Dest. Src. Port outbound ICMP traffic.
Services
Type: Range:
Network
Service n/a
Dest.
Port
Range:
n/a
5 State: All <region> Protocol: n/a Allows: TCP traffic for ports: 80.
Stateful Services in TCP
Description: This rule enables worker
Oracle
Dest. Src. Port nodes to communicate with Container
Services
Type: Range: Engine for Kubernetes to ensure correct
Network
Service 80 start-up, and continued functioning.
Dest.
Port
Range:
80
6 State: All <region> Protocol: n/a Allows: TCP traffic for ports: 443
Stateful Services in TCP
Description: This rule enables worker
Oracle
Dest. Src. Port nodes to communicate with Container
Services
Type: Range: Engine for Kubernetes to ensure correct
Network
Service 443 start-up, and continued functioning.
Dest.
Port
Range:
443
7 State: All <region> Protocol: n/a Allows: TCP traffic for ports: 6443
Stateful Services in TCP
Description: This rule enables worker
Oracle
Dest. Src. Port nodes to communicate with Container
Services
Type: Range: Engine for Kubernetes to ensure correct
Network
Service 6443 start-up, and continued functioning.
Dest.
Port
Range:
6443
8 State: All <region> Protocol: n/a Allows: TCP traffic for ports: 12250
Stateful Services in TCP
Description: This rule enables worker
Oracle
Dest. Src. Port nodes to communicate with Container
Services
Type: Range: Engine for Kubernetes to ensure correct
Network
Service 12250 start-up, and continued functioning.
Dest.
Port
Range:
12250
Example Ingress Rules in the 'loadbalancers' Security List for Load Balancer AD-
Specific Subnets:
If you want to allow unrestricted incoming traffic through the load balancer from the public
1 State: 0.0.0.0/0 Protocol: n/a Allows: TCP traffic for all ports: all
Stateless TCP
Description: This rule enables incoming
Src. Src. Port public traffic to service load balancers.
Type: Range: All
CIDR
Dest. Port
Range: All
Alternatively, if you want to restrict incoming traffic through the load balancer to just that
coming from a particular public CIDR range (for example, 160.34.126.216/30), set up the
following security rule:
1 State: 160.34.126.216/30 Protocol: n/a Allows: TCP traffic for all ports: all
Stateful TCP
Description: This rule only allows
Src. Src. Port incoming public traffic to service
Type: Range: load balancers from a particular
CIDR All public CIDR range.
Dest.
Port
Range:
All
Example Egress Rules in the 'loadbalancers' Security List for Load Balancer AD-
Specific Subnets:
If you want to allow unrestricted outgoing response traffic through the load balancer to the
public internet, set up the following security rules:
1 State: 0.0.0.0/0 Protocol: n/a Allows: TCP traffic for ports: all
Stateless TCP
Description: This rule enables responses
Dest. Src. Port from a web application through the service
Type: Range: load balancers.
CIDR All
Dest.
Port
Range:
All
Alternatively, if you want to restrict outgoing response traffic through the load balancer to just
that going to worker node subnets in the cluster, set up the following security rules:
1 State: 10.0.10.0/24 Protocol: n/a Allows: TCP traffic for ports: all
Stateful TCP
Description: This rule restricts
Dest. Src. Port responses of the web application to the
Type: Range: All workers-1 subnet.
CIDR
Dest.
Port
Range: All
2 State: 10.0.11.0/24 Protocol: n/a Allows: TCP traffic for ports: all
Stateful TCP
Description: This rule restricts
Dest. Src. Port responses of the web application to the
Type: Range: All workers-2 subnet.
CIDR
Dest.
Port
Range: All
3 State: 10.0.12.0/24 Protocol: n/a Allows: TCP traffic for ports: all
Stateful TCP
Description: This rule restricts
Dest. Src. Port responses of the web application to the
Type: Range: All workers-3 subnet.
CIDR
Dest.
Port
Range: All
This example assumes you want worker nodes hosted in three private AD-specific subnets
that can only be accessed from within the VCN.
Resource Example
l Name: acme-dev-vcn
l CIDR Block: 10.0.0.0/16
l DNS Resolution: Selected
l Name: nat-gateway-0
Resource Example
Route Table Two route tables created manually, named, and defined as follows:
Note that to avoid the possibility of asymmetric routing, a route table for a
public subnet cannot contain both a route rule that targets an internet
gateway as well as a route rule that targets a service gateway (for more
information, see Issues with access from Oracle services through a service
gateway to your public instances).
Resource Example
Security Lists Two created (in addition to the default security list) manually, named, and
defined as follows:
For details of the ingress rules and egress rules defined for these security
lists, see Example Security List Configurations for a Highly Available Private
Cluster Using AD-Specific Subnets.
Resource Example
Subnets Three worker node AD-specific subnets created manually, named, and
defined as follows:
Resource Example
EXAMPLE S ECURITY LIST CONFIGURATIONS FOR A HIGHLY AVAILABLE PRIVATE CLUSTER USING AD-
S PECIFIC S UBNETS
In the example VCN, two security lists have been created (in addition to the default security
list) to control access to and from the private worker node AD-specific subnets and the load
balancer AD-specific subnets. The two security lists are named 'workers' and 'loadbalancers'
respectively.
Example Ingress Rules in the 'workers' Security List for Private Worker Node AD-
Specific Subnets:
1 State: 10.0.10.0/24 Protocol: n/a Allows: All traffic for all ports
Stateless All
Description: This optional rule enables
Src. Src. Port intra-VCN traffic. Although optional, this
Type: Range: rule is usually necessary to enable pods
CIDR n/a on one worker node to communicate
with pods on other worker nodes.Only in
Dest.
the rare case where no inter-pod
Port
communication is expected, is this rule
Range:
not required.
n/a
2 State: 10.0.11.0/24 Protocol: n/a Allows: All traffic for all ports
Stateless All
Description: This optional rule enables
Src. Src. Port intra-VCN traffic. Although optional, this
Type: Range: rule is usually necessary to enable pods
CIDR n/a on one worker node to communicate
with pods on other worker nodes. In the
Dest.
rare case where no inter-pod
Port
communication is expected, this rule is
Range:
not required.
n/a
3 State: 10.0.12.0/24 Protocol: n/a Allows: All traffic for all ports
Stateless All
Description: This optional rule enables
Src. Src. Port intra-VCN traffic. Although optional, this
Type: Range: rule is usually necessary to enable pods
CIDR n/a on one worker node to communicate
with pods on other worker nodes. In the
Dest.
rare case where no inter-pod
Port
communication is expected, this rule is
Range:
not required.
n/a
4 State: 10.0.0.0/16 Protocol: n/a Allows: TCP traffic for ports: 22 SSH
Stateful TCP Remote Login Protocol
Dest.
Port
Range:
22
Example Egress Rules in the 'workers' Security List for Private Worker Node AD-
Specific Subnets:
Consider these egress rules as a minimum requirement. If applications deployed on worker
nodes need to communicate with destinations outside of the Oracle Service Network, add
additional egress rules. For example, if applications use Helm charts from the Helm stable
repository, or Docker images from docker.io.
1 State: 10.0.10.0/24 Protocol: n/a Allows: All traffic for all ports
Stateless All
Description: This optional rule enables
Dest. Src. Port intra-VCN traffic. Although optional, this
Type: Range: rule is usually necessary to enable pods
CIDR n/a on one worker node to communicate
with pods on other worker nodes. Only
Dest.
in the rare case where no inter-pod
Port
communication is expected, is this rule
Range:
not required.
n/a
2 State: 10.0.11.0/24 Protocol: n/a Allows: All traffic for all ports
Stateless All
Description: This optional rule enables
Dest. Src. Port intra-VCN traffic. Although optional, this
Type: Range: rule is usually necessary to enable pods
CIDR n/a on one worker node to communicate
with pods on other worker nodes. Only
Dest.
in the rare case where no inter-pod
Port
communication is expected, is this rule
Range:
not required.
n/a
3 State: 10.0.12.0/24 Protocol: n/a Allows: All traffic for all ports
Stateless All
Description: This optional rule enables
Src. Port
Dest. intra-VCN traffic. Although optional, this
Range:
Type: rule is usually necessary to enable pods
n/a
CIDR on one worker node to communicate
Dest.
with pods on other worker nodes. Only
Port
in the rare case where no inter-pod
Range:
communication is expected, is this rule
n/a
not required.
4 State: All <region> Protocol: All Allows: ICMP traffic for all ports.
Stateful Services in ICMP
Description: This rule enables
Oracle Src. Port
Dest. outbound ICMP traffic.
Services Range:
Type:
Network n/a
Service
Dest.
Port
Range:
n/a
5 State: All <region> Protocol: n/a Allows: TCP traffic for ports: 80.
Stateful Services in TCP
Description: This rule enables worker
Oracle
Dest. Src. Port nodes to communicate with Container
Services
Type: Range: Engine for Kubernetes to ensure correct
Network
Service 80 start-up, and continued functioning.
Dest.
Port
Range:
80
6 State: All <region> Protocol: n/a Allows: TCP traffic for ports: 443
Stateful Services in TCP
Description: This rule enables worker
Oracle
Dest. Src. Port nodes to communicate with Container
Services
Type: Range: Engine for Kubernetes to ensure correct
Network
Service 443 start-up, and continued functioning.
Dest.
Port
Range:
443
7 State: All <region> Protocol: n/a Allows: TCP traffic for ports: 6443
Stateful Services in TCP
Description: This rule enables worker
Oracle
Dest. Src. Port nodes to communicate with Container
Services
Type: Range: Engine for Kubernetes to ensure correct
Network
Service 6443 start-up, and continued functioning.
Dest.
Port
Range:
6443
8 State: All <region> Protocol: n/a Allows: TCP traffic for ports: 12250
Stateful Services in TCP
Description: This rule enables worker
Oracle
Dest. Src. Port nodes to communicate with Container
Services
Type: Range: Engine for Kubernetes to ensure correct
Network
Service 12250 start-up, and continued functioning.
Dest.
Port
Range:
12250
Example Ingress Rules in the 'loadbalancers' Security List for a Load Balancer AD-
Specific Subnet:
1 State: 0.0.0.0/0 Protocol: n/a Allows: TCP traffic for all ports: all
Stateless TCP
Description: This rule enables incoming
Src. Src. Port public traffic to service load balancers.
Type: Range: All
CIDR
Dest. Port
Range: All
Example Egress Rules in the 'loadbalancers' Security List for a Load Balancer AD-
Specific Subnet:
1 State: 0.0.0.0/0 Protocol: n/a Allows: TCP traffic for ports: all
Stateless TCP
Description: This rule enables responses
Src. Port
Dest. from a web application through the service
Range:
Type: load balancers.
All
CIDR
Dest.
Port
Range:
All
This example assumes you want worker nodes hosted in a public regional subnet that can be
accessed directly from the internet.
Resource Example
l Name: acme-dev-vcn
l CIDR Block: 10.0.0.0/16
l DNS Resolution: Selected
Resource Example
Route Table Two route tables created manually, named, and defined as follows:
Note that to avoid the possibility of asymmetric routing, a route table for a
public subnet cannot contain both a route rule that targets an internet
gateway as well as a route rule that targets a service gateway (for more
information, see Issues with access from Oracle services through a service
gateway to your public instances).
Resource Example
Security Lists Two created (in addition to the default security list) manually, named, and
defined as follows:
For details of the ingress rules and egress rules defined for the workers
security list and the loadbalancers security list, see Example Security List
Configurations for a Highly Available Public Cluster using Regional Subnets.
Subnets One worker node regional subnet created manually, named, and defined as
follows:
One load balancer regional subnet created, named, and defined as follows:
EXAMPLE S ECURITY LIST CONFIGURATIONS FOR A HIGHLY AVAILABLE PUBLIC CLUSTER USING REGIONAL
S UBNETS
In the example VCN, two security lists have been created (in addition to the default security
list) to control access to and from a public worker node regional subnet and a load balancer
regional subnet. The two security lists are named 'workers' and 'loadbalancers' respectively.
Example Ingress Rules in the 'workers' Security List for a Public Worker Node
Regional Subnet:
1 State: 10.0.10.0/24 Protocol: n/a Allows: All traffic for all ports
Stateless All
Description: This optional rule enables
Src. Src. Port intra-VCN traffic. Although optional, this
Type: Range: rule is usually necessary to enable pods
CIDR n/a on one worker node to communicate
with pods on other worker nodes. Only
Dest.
in the rare case where no inter-pod
Port
communication is expected, is this rule
Range:
not required.
n/a
3 State: 0.0.0.0/0 Protocol: n/a Allows: TCP traffic for ports: 22 SSH
Stateful TCP Remote Login Protocol
Dest.
Port
Range:
22
4 State: 0.0.0.0/0 Protocol: n/a Allows: TCP traffic for ports: 30000 -
Stateful TCP 32767
Example Egress Rules in the 'workers' Security List for a Public Worker Node Regional
Subnet:
Consider these egress rules as a minimum requirement. If applications deployed on worker
nodes need to communicate with destinations outside of the Oracle Service Network, add
additional egress rules. For example, if applications use Helm charts from the Helm stable
repository, or Docker images from docker.io.
1 State: 10.0.10.0/24 Protocol: n/a Allows: All traffic for all ports
Stateless All
Description: This optional rule enables
Dest. Src. Port intra-VCN traffic. Although optional, this
Type: Range: rule is usually necessary to enable pods
CIDR n/a on one worker node to communicate
with pods on other worker nodes. Only
Dest.
in the rare case where no inter-pod
Port
communication is expected, is this rule
Range:
not required.
n/a
2 State: All <region> Protocol: All Allows: ICMP traffic for all ports.
Stateful Services in ICMP
Description: This rule enables
Oracle
Dest. Src. Port outbound ICMP traffic.
Services
Type: Range:
Network
Service n/a
Dest.
Port
Range:
n/a
3 State: All <region> Protocol: n/a Allows: TCP traffic for ports: 80.
Stateful Services in TCP
Description: This rule enables worker
Oracle
Dest. Src. Port nodes to communicate with Container
Services
Type: Range: Engine for Kubernetes to ensure correct
Network
Service 80 start-up, and continued functioning.
Dest.
Port
Range:
80
4 State: All <region> Protocol: n/a Allows: TCP traffic for ports: 443
Stateful Services in TCP
Description: This rule enables worker
Oracle
Dest. Src. Port nodes to communicate with Container
Services
Type: Range: Engine for Kubernetes to ensure correct
Network
Service 443 start-up, and continued functioning.
Dest.
Port
Range:
443
5 State: All <region> Protocol: n/a Allows: TCP traffic for ports: 6443
Stateful Services in TCP
Description: This rule enables worker
Oracle
Dest. Src. Port nodes to communicate with Container
Services
Type: Range: Engine for Kubernetes to ensure correct
Network
Service 6443 start-up, and continued functioning.
Dest.
Port
Range:
6443
6 State: All <region> Protocol: n/a Allows: TCP traffic for ports: 12250
Stateful Services in TCP
Description: This rule enables worker
Oracle
Dest. Src. Port nodes to communicate with Container
Services
Type: Range: Engine for Kubernetes to ensure correct
Network
Service 12250 start-up, and continued functioning.
Dest.
Port
Range:
12250
Example Ingress Rules in the 'loadbalancers' Security List for a Load Balancer
Regional Subnet:
1 State: 0.0.0.0/0 Protocol: n/a Allows: TCP traffic for all ports: all
Stateless TCP
Description: This rule enables incoming
Src. Src. Port public traffic to service load balancers.
Type: Range: All
CIDR
Dest. Port
Range: All
Example Egress Rules in the 'loadbalancers' Security List for a Load Balancer
Regional Subnet:
1 State: 0.0.0.0/0 Protocol: n/a Allows: TCP traffic for ports: all
Stateless TCP
Description: This rule enables responses
Dest. Src. Port from a web application through the service
Type: Range: load balancers.
CIDR All
Dest.
Port
Range:
All
When creating a cluster with Container Engine for Kubernetes, you specify:
l The CIDR block you specify for the VCN must not overlap with the CIDR block you
specify for the Kubernetes services.
l The CIDR blocks you specify for pods running in the cluster must not overlap with
CIDR blocks you specify for worker node and load balancer subnets.
l Each pod running on a worker node is assigned its own network address. Container
Engine for Kubernetes allocates a /24 CIDR block of network addresses for each worker
node in a cluster, to assign to pods running on that node. A /24 CIDR block equates to
256 distinct IP addresses, of which one is reserved. So a maximum of 255 network
addresses are available to assign to pods running on each worker node (more than
sufficient, given that the number of pods per node is capped at 110).
l When you create a cluster, you specify a value for the cluster's Pods CIDR Block
property, either implicitly in the case of a 'quick cluster' or explicitly in the case of a
'custom cluster'. You cannot change the cluster's Pods CIDR Block property after the
cluster has been created. The cluster's Pods CIDR Block property constrains the
maximum total number of network addresses available for allocation to pods running on
all the nodes in the cluster, and therefore effectively limits the number of nodes in the
cluster. By default, the cluster's Pods CIDR Block property is set to a /16 CIDR block,
making 65,536 network addresses available for all the nodes in the cluster. Since 256
network addresses are allocated for each node, specifying a /16 CIDR block for the
cluster's Pods CIDR Block property limits the number of nodes in the cluster to 256.
This is generally sufficient. To support more than 256 nodes in a cluster, create a
'custom cluster' and specify a larger value for the cluster's Pods CIDR Block property
when you create the cluster. For example, specify a /14 CIDR block for the cluster's
Pods CIDR Block property to create a cluster with 262,144 network addresses
available for the nodes in the cluster (more than sufficient, given that the number of
nodes per cluster is capped at 1000).
in the tenancy. If all the users that will be working with Container Engine for Kubernetes are
already members of the Administrators group, there's no need to create additional policies.
However, if you want to enable users that are not members of the Administrators group to use
Container Engine for Kubernetes, you must create policies to enable the groups to which those
users do belong to perform operations on resources in the tenancy or in individual
compartments. Some policies are required, some are optional. See Create Required Policy for
Groups and Create One or More Additional Policies for Groups.
Note that in addition to the above policies managed by IAM, you can also use the Kubernetes
RBAC Authorizer to enforce additional fine-grained access control for users on specific
clusters via Kubernetes RBAC roles and clusterroles. See About Access Control and Container
Engine for Kubernetes.
To create, update, and delete clusters and node pools, users that are not members of the
Administrators group must have permissions to work with cluster-related resources. To give
users the necessary access, you must create a policy with a number of required policy
statements for the groups to which those users do belong:
1. In the Console, open the navigation menu. Under Governance and Administration,
go to Identity and click Policies. A list of the policies in the compartment you're
viewing is displayed.
2. Select the tenancy's root compartment or an individual compartment containing cluster-
related resources from the list on the left.
3. Click Create Policy.
4. Enter the following:
l Name: A name for the policy (for example, acme-dev-team-oke-required-
policy) that is unique within the compartment. If you are creating the policy in
the tenancy's root compartment, the name must be unique across all policies in
your tenancy. You cannot change this later. Avoid entering confidential
information.
l Description: A friendly description. You can change this later if you want to.
Avoid entering confidential information.
l Policy Versioning: Select Keep Policy Current if you'd like the policy to stay
current with any future changes to the service's definitions of verbs and
resources. Or if you'd prefer to limit access according to the definitions that were
current on a specific date, select Use Version Date and enter that date in YYYY-
MM-DD format. For more information, see Policy Language Version.
l Statement: The following required policy statements to enable users to use
Container Engine for Kubernetes to create, update, and delete clusters and node
pools:
o Allow group <group-name> to manage instance-family in
<location>
o Allow group <group-name> to use subnets in <location>
o Allow group <group-name> to read virtual-network-family in
<location>
o Allow group <group-name> to use vnics in <location>
o Allow group <group-name> to inspect compartments in <location>
The following required policy statement to enable users to perform any operation
on cluster-related resources (this 'catch-all' policy effectively makes all users
administrators insofar as cluster-related resources are concerned):
o Allow group <group-name> to manage cluster-family in <location>
In the above policy statements, replace <location> with either tenancy (if you
are creating the policy in the tenancy's root compartment) or compartment
<compartment-name> (if you are creating the policy in an individual
compartment).
l Tags: Optionally, you can apply 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.
5. Click Create.
To enable users that are not members of the Administrators group to use Container Engine for
Kubernetes, create additional policies to enable the groups to which those users do belong to
perform operations on cluster-related resources as follows:
1. In the Console, open the navigation menu. Under Governance and Administration,
go to Identity and click Policies. A list of the policies in the compartment you're
viewing is displayed.
2. Select the tenancy's root compartment or an individual compartment containing cluster-
related resources from the list on the left.
3. Click Create Policy.
4. Enter the following:
l Name: A name for the policy (for example, acme-dev-team-oke-additional-
policy) that is unique within the compartment. If you are creating the policy in
the tenancy's root compartment, the name must be unique across all policies in
your tenancy. You cannot change this later. Avoid entering confidential
information.
l Description: A friendly description. You can change this later if you want to.
Avoid entering confidential information.
l Policy Versioning: Select Keep Policy Current if you'd like the policy to stay
current with any future changes to the service's definitions of verbs and
resources. Or if you'd prefer to limit access according to the definitions that were
current on a specific date, select Use Version Date and enter that date in YYYY-
MM-DD format. For more information, see Policy Language Version.
You first specify basic details for the new cluster (the cluster name, and the Kubernetes
version to install on master nodes). You can then create the cluster in one of two ways:
l Using default settings to create a 'quick cluster' with new network resources as
required. This approach is the fastest way to create a new cluster. If you accept all the
default values, you can create a new cluster in just a few clicks. New network resources
for the 'quick cluster' are created automatically, including one regional subnet for
worker nodes, and another regional subnet for load balancers. The regional subnet for
load balancers will be public, but you can specify whether the regional subnet for
worker nodes will be public or private. Note that if you specify a private regional subnet
for worker nodes in the 'quick cluster', a NAT gateway is also created (in addition to an
internet gateway). To create a 'quick cluster', you must belong to a group to which a
policy grants the necessary permissions to create the new network resources (see
Create One or More Additional Policies for Groups).
l Using custom settings to create a 'custom cluster'. This approach gives you the most
control over the new cluster. You can explicitly define the new cluster's properties. And
you can explicitly specify which existing network resources to use, including the existing
public or private subnets in which to create worker nodes and load balancers. The
subnets can be regional subnets (recommended) or AD-specific subnets. Note that
although you will usually define node pools immediately when defining a new 'custom
cluster', you don't have to. You can create a 'custom cluster' with no node pools, and
add node pools later.
Regardless of how you create a cluster, Container Engine for Kubernetes gives names to
worker nodes in the following format:
oke-c<part-of-cluster-OCID>-n<part-of-node-pool-OCID>-s<part-of-subnet-OCID>-
<slot>
where:
l oke is the standard prefix for all worker nodes created by Container Engine for
Kubernetes
l c<part-of-cluster-OCID> is a portion of the cluster's OCID, prefixed with the letter c
l n<part-of-node-pool-OCID> is a portion of the node pool's OCID, prefixed with the
letter n
l s<part-of-subnet-OCID> is a portion of the subnet's OCID, prefixed with the letter s
l <slot> is an ordinal number of the node in the subnet (for example, 0, 1)
For example, if you specified a cluster is to have two nodes in a node pool, the two nodes
might be named:
l oke-cywiqripuyg-nsgagklgnst-st2qczvnmba-0
l oke-cywiqripuyg-nsgagklgnst-st2qczvnmba-1
Do not change the auto-generated names that Container Engine for Kubernetes gives to
worker nodes.
1. In the Console, open the navigation menu. Under Solutions and Platform, go to
Developer Services and click Container Clusters.
2. Choose a Compartment you have permission to work in.
3. On the Cluster List page, click Create Cluster.
4. In the Create Cluster dialog, select Quick Create and click Launch Workflow.
5. On the Create Cluster page, either just accept the default configuration details for the
new cluster, or specify alternatives as follows:
l Name: The name of the new cluster. Either accept the default name or enter a
name of your choice. Avoid entering confidential information.
l Compartment: The compartment in which to create the new cluster and the
associated network resources.
l Kubernetes Version: The version of Kubernetes to run on the master nodes and
worker nodes of the cluster. Either accept the default version or select a version
of your choice. Amongst other things, the Kubernetes version you select
determines the default set of admission controllers that are turned on in the
created cluster (see Supported Admission Controllers).
l Visibility Type: Whether to create a private or a public regional subnet to host
worker nodes (note that a public regional subnet is always created to host load
balancers in a 'quick cluster', regardless of your selection here):
o Private: Select to create a private regional subnet to host worker nodes
(along with the public regional subnet to host load balancers).
o Public: Select to create a public regional subnet to host worker nodes
(along with the public regional subnet to host load balancers).
l Shape: The shape to use for each node in the node pool. The shape determines
the number of CPUs and the amount of memory allocated to each node. The list
shows only those shapes available in your tenancy that are supported by
Container Engine for Kubernetes. See Supported Images (Including Custom
Images) and Shapes for Worker Nodes.
l Number of Nodes: The number of worker nodes to create in the node pool,
placed in the regional subnet created for the 'quick cluster'. The nodes are
distributed as evenly as possible across the availability domains in a region (or in
the case of a region with a single availability domain, across the fault domains in
that availability domain).
6. Either accept the defaults for advanced cluster options, or click Show Advanced
Options and specify alternatives as follows:
l Public SSH Key: (Optional) The public key portion of the key pair you want to
use for SSH access to each node in the node pool. The public key is installed on all
worker nodes in the cluster. Note that if you don't specify a public SSH key,
Container Engine for Kubernetes will provide one. However, since you won't have
the corresponding private key, you will not have SSH access to the worker nodes.
Note that if you specify that you want the worker nodes in the 'quick cluster' to be
hosted in a private regional subnet, you cannot use SSH to access them directly
(see Connecting to Worker Nodes in Private Subnets Using SSH).
l Kubernetes Labels: (Optional) One or more labels (in addition to a default label)
to add to worker nodes in the node pool to enable the targeting of workloads at
specific node pools.
7. Either accept the defaults for add-ons, or specify alternatives:
l Kubernetes Dashboard Enabled: Select if you want to use the Kubernetes
Dashboard to deploy and troubleshoot containerized applications, and to manage
Kubernetes resources. Note that you cannot run the Kubernetes Dashboard in
Cloud Shell. See Starting the Kubernetes Dashboard.
8. Click Next to review the details you entered for the new cluster.
9. Click Create Cluster to create the new network resources and the new cluster.
Container Engine for Kubernetes starts creating resources (as shown in the Creating
cluster and associated network resources dialog):
l the network resources (such as the VCN, internet gateway, NAT gateway, route
tables, security lists, a regional subnet for worker nodes and another regional
subnet for load balancers), with auto-generated names in the format oke-
<resource-type>-quick-<cluster-name>-<creation-date>
Do not change the resource names that Container Engine for Kubernetes has auto-
generated. Note that if the cluster is not created successfully for some reason (for
example, if you have insufficient permissions or if you've exceeded the cluster limit for
the tenancy), any network resources created during the cluster creation process are not
deleted automatically. You will have to manually delete any such unused network
resources.
10. Click Close to return to the Console.
Initially, the new cluster appears in the Console with a status of Creating. When the cluster
has been created, it has a status of Active.
Container Engine for Kubernetes also creates a Kubernetes kubeconfig configuration file that
you use to access the cluster using kubectl and the Kubernetes Dashboard.
1. In the Console, open the navigation menu. Under Solutions and Platform, go to
Developer Services and click Container Clusters.
2. Choose a Compartment you have permission to work in.
3. On the Cluster List page, click Create Cluster.
4. In the Create Cluster dialog, select Custom Create and click Launch Workflow.
5. On the Create Cluster page, either just accept the default configuration details for the
new cluster, or specify alternatives as follows:
l Name: The name of the new cluster. Either accept the default name or enter a
name of your choice. Avoid entering confidential information.
l Compartment: The compartment in which to create the new cluster.
l Kubernetes Version: The version of Kubernetes to run on the master nodes and
worker nodes of the cluster. Either accept the default version or select a version
of your choice. Amongst other things, the Kubernetes version you select
determines the default set of admission controllers that are turned on in the
created cluster (see Supported Admission Controllers).
6. Either accept the defaults for advanced cluster options, or click Show Advanced
Warning
8. Click Next and specify the existing network resources to use for the new cluster on the
Network Setup page:
l VCN in <compartment-name>: The existing virtual cloud network that has
been configured for cluster creation and deployment. By default, <compartment-
name> is the compartment in which you are creating the cluster, but you can
select a different compartment by clicking Change Compartment. See VCN
Configuration.
l Kubernetes Service LB Subnets: Optionally, the existing subnets that have
been configured to host load balancers. Load balancer subnets must be different
from worker node subnets, can be public or private, and can be regional
(recommended) or AD-specific. You don't have to specify any load balancer
subnets. However, if you do specify load balancer subnets, the number of load
balancer subnets to specify depends on the region in which you are creating the
cluster and whether the subnets are regional or AD-specific.
If you are creating a cluster in a region with three availability domains, you can
specify:
o Zero or one load balancer regional subnet (recommended).
o Zero or two load balancer AD-specific subnets. If you specify two AD-
specific subnets, the two subnets must be in different availability domains.
If you are creating a cluster in a region with a single availability domain, you can
specify:
o Zero or one load balancer regional subnet (recommended).
o Zero or one load balancer AD-specific subnet.
See Subnet Configuration.
9. Either accept the defaults for advanced cluster options, or click Show Advanced
Options and specify alternatives as follows:
l Kubernetes Service CIDR Block: The available group of network addresses
that can be exposed as Kubernetes services (ClusterIPs), expressed as a single,
contiguous IPv4 CIDR block. For example, 10.96.0.0/16. The CIDR block you
specify must not overlap with the CIDR block for the VCN. See CIDR Blocks and
If you specified details for one or more node pools, Container Engine for Kubernetes
creates:
l node pools with the names you specified
l worker nodes with auto-generated names in the format oke-c<part-of-
cluster-OCID>-n<part-of-node-pool-OCID>-s<part-of-subnet-OCID>-
<slot>
Initially, the new cluster appears in the Console with a status of Creating. When the cluster
has been created, it has a status of Active.
Container Engine for Kubernetes also creates a Kubernetes kubeconfig configuration file that
you use to access the cluster using kubectl and the Kubernetes Dashboard.
The steps to follow when setting up the kubeconfig file depend on how you want to access the
cluster:
l To access the cluster using kubectl in Cloud Shell, run an Oracle Cloud Infrastructure
CLI command in the Cloud Shell window to set up the kubeconfig file. Note that you
cannot run the Kubernetes Dashboard in Cloud Shell. See Setting Up Cloud Shell Access
to Clusters.
l To access the cluster using a local installation of kubectl and the Kubernetes Dashboard:
o Generate an API signing key pair (if you don't already have one).
o Upload the public key of the API signing key pair.
o Install and configure the Oracle Cloud Infrastructure CLI.
o Set up the kubeconfig file.
See Setting Up Local Access to Clusters.
For example, enter the following command (or copy and paste it from the Access Your
Cluster dialog box) in the Cloud Shell window:
$ oci ce cluster create-kubeconfig --cluster-id ocid1.cluster.oc1.phx.aaaaaaaaae... --file
$HOME/.kube/config --region us-phoenix-1 --token-version 2.0.0
Tip
8. If you don't save the kubeconfig file in the default location ($HOME/.kube) or with the
default name (config), set the value of the KUBECONFIG environment variable to point
to the name and location of the kubeconfig file. For example, enter the following
command in the Cloud Shell window:
$ export KUBECONFIG=$HOME/.kube/config
1. Use OpenSSL commands to generate the key pair in the required PEM format. If you're
using Windows, you'll need to install Git Bash for Windows and run the commands with
that tool. See How to Generate an API Signing Key.
2. Copy the contents of the public key to the clipboard (you'll need to paste the value into
the Console later).
7. Run the Oracle Cloud Infrastructure CLI command to set up the kubeconfig file and save
it in a location accessible to kubectl and the Kubernetes Dashboard.
For example, on Linux, enter the following command (or copy and paste it from the
Access Your Cluster dialog box) in a local terminal window:
$ oci ce cluster create-kubeconfig --cluster-id ocid1.cluster.oc1.phx.aaaaaaaaae... --file
$HOME/.kube/config --region us-phoenix-1 --token-version 2.0.0
following command (or copy and paste it from the Access Your Cluster dialog box) in
a local terminal window:
$ export KUBECONFIG=$HOME/.kube/config
l A single kubeconfig file can include the details for multiple clusters, as multiple
contexts. The cluster on which operations will be performed is specified by the
current-context: element in the kubeconfig file.
l A kubeconfig file includes an Oracle Cloud Infrastructure CLI command that dynamically
generates an authentication token and inserts it when you run a kubectl command. The
Oracle Cloud Infrastructure CLI must be available on your shell's executable path (for
example, $PATH on Linux).
l The authentication tokens generated by the Oracle Cloud Infrastructure CLI command in
the kubeconfig file are short-lived, cluster-scoped, and specific to individual users. As a
result, you cannot share kubeconfig files between users to access Kubernetes clusters.
l The Oracle Cloud Infrastructure CLI command in the kubeconfig file uses your current
CLI profile when generating an authentication token. If you have defined multiple
profiles in different tenancies in the CLI configuration file (for example, in
~/.oci/config), specify which profile to use when generating the authentication token as
follows. In both cases, <profile-name> is the name of the profile defined in the
CLI configuration file:
o Add --profile to the args: section of the kubeconfig file as follows:
user:
exec:
apiVersion: client.authentication.k8s.io/v1beta1
args:
- ce
- cluster
- generate-token
- --cluster-id
- <cluster ocid>
- --profile
- <profile-name>
command: oci
env: []
o Set the OCI_CLI_PROFILE environment variable to the name of the profile defined
in the CLI configuration file before running kubectl commands. For example:
$ export OCI_CLI_PROFILE=<profile-name>
$ kubectl get nodes
l The authentication tokens generated by the Oracle Cloud Infrastructure CLI command in
the kubeconfig file are appropriate to authenticate individual users accessing the cluster
using kubectl and the Kubernetes Dashboard. However, the generated authentication
tokens are unsuitable if you want other processes and tools to access the cluster, such
as continuous integration and continuous delivery (CI/CD) tools. In this case, consider
creating a Kubernetes service account and adding its associated authentication token to
the kubeconfig file. For more information, see Adding a Service Account Authentication
Token to a Kubeconfig File.
Enhancements in kubeconfig version 2.0.0 files provide security improvements for your
Kubernetes environment, including short-lived cluster-scoped tokens with automated
refreshing, and support for instance principals to access Kubernetes clusters. Additionally,
authentication tokens are generated on-demand for each cluster, so kubeconfig version 2.0.0
files cannot be shared between users to access Kubernetes clusters (unlike kubeconfig version
1.0.0 files).
Note that kubeconfig version 2.0.0 files are not compatible with kubectl versions prior to
version 1.11.9. If you are currently running kubectl version 1.10.x or older, upgrade kubectl
to version 1.11.9 or later. For more information about compatibility between different
versions of kubernetes and kubectl, see the Kubernetes documentation.
Follow the instructions below to determine the current version of kubeconfig files, and how to
upgrade any remaining kubeconfig version 1.0.0 files to version 2.0.0.
1. In a terminal window (the Cloud Shell window or a local terminal window as appropriate),
enter the following command to see the format of the kubeconfig file currently pointed at by
the KUBECONFIG environment variable:
$ kubectl config view
2. If the kubeconfig file is version 1.0.0, you see a response in the following format:
users:
- name: <username>
user:
token: <token-value>
If you see a response in the above format, you have to upgrade the kubeconfig file. See
Upgrade a kubeconfig version 1.0.0 file to version 2.0.0.
3. If the kubeconfig file is version 2.0.0, you see a response in the following format:
user:
exec:
apiVersion: client.authentication.k8s.io/v1beta1
args:
- ce
- cluster
- generate-token
- --cluster-id
- <cluster ocid>
command: oci
env: []
1. In the case of a local installation of kubectl, confirm that Oracle Cloud Infrastructure CLI
version 2.6.4 (or later) is installed by entering:
oci -version
If the Oracle Cloud Infrastructure CLI version is earlier than version 2.6.4, upgrade the
CLI to a later version. See Upgrading the CLI.
2. Follow the appropriate instructions to set up the kubeconfig file for use in Cloud Shell or
locally (see Setting Up Cloud Shell Access to Clusters or Setting Up Local Access to
Clusters). Running the oci ce cluster create-kubeconfig command shown in the
Access Your Cluster dialog box upgrades the existing kubeconfig version 1.0.0 file. If
you change the name or location of the kubeconfig file, set the KUBECONFIG
environment variable to point to the new name and location of the file.
3. Confirm the kubeconfig file is now version 2.0.0:
a. In a terminal window (the Cloud Shell window or a local terminal window as
appropriate), enter:
$ kubectl config view
l the number of node pools in a cluster by adding new node pools, or deleting existing
node pools
Also note that you must not change the auto-generated names of resources that Container
Engine for Kubernetes has created (such as the names of worker nodes).
1. In the Console, open the navigation menu. Under Solutions and Platform, go to
Developer Services and click Container Clusters.
2. Choose a Compartment you have permission to work in.
3. On the Cluster List page, click the name of the cluster you want to modify.
4. Use the buttons across the top of the Cluster page as follows:
l If you want to set up the kubeconfig configuration file for the cluster, click the
Access Cluster button (see Setting Up Cluster Access).
l If you want to delete the cluster along with its master nodes and worker nodes,
click the Delete Cluster button.
l If a newer version of Kubernetes is available than the one running on the master
nodes in the cluster, the Upgrade button is enabled. If you want to upgrade the
master nodes to a newer version, click Upgrade (see Upgrading the Kubernetes
Version on Master Nodes in a Cluster).
5. Use the Cluster Details tab to see information about the cluster, including:
l The status of the cluster, and of the node pools in the cluster.
l The cluster's OCID.
l The Kubernetes version running on the master nodes in the cluster. If a newer
version of Kubernetes is available than the one running on the master nodes in the
cluster, the Upgrade link is shown. If you want to upgrade the master nodes to a
newer version, click the Upgrade link (see Upgrading the Kubernetes Version on
Master Nodes in a Cluster).
l The address of the Kubernetes endpoint.
l Whether pod security policies are being enforced (by enabling the cluster's
PodSecurityPolicy admission controller). Note that you must create pod security
policies before enabling the PodSecurityPolicy admission controller of an existing
cluster that is already in production. We also strongly recommend you first verify
the cluster's pod security policies in a development or test environment. That
way, you can be sure the pod security policies work as you expect and correctly
allow (or refuse) pods to start on the cluster. Also note that if you disable a
cluster's PodSecurityPolicy admission controller, any pod security policies (along
with roles, rolebindings, clusterroles, and clusterrolebindings) you've defined are
not deleted, they are simply not enforced. See Using Pod Security Polices with
Container Engine for Kubernetes.
6. Use the Node Pools tab to:
l View information about each of the node pools in the cluster, including:
o The status of the node pool.
o The node pool's OCID.
o The configuration currently used when starting new worker nodes in the
node pool, including the Kubernetes version, the shape, and the image.
o The availability domains, and different regional subnets (recommended) or
AD-specific subnets hosting worker nodes.
Note that you can change some of these node pool and worker node properties
(see Modifying Node Pool and Worker Node Properties).
l Add a new node pool to the cluster by clicking the Add Node Pool button and
entering details for the new node pool.
l Delete a node pool by selecting Delete Node Pool from the Actions menu.
7. Use the Quick Start tab to:
l Set up access to the cluster (see Setting Up Cluster Access).
l Download and deploy a sample Nginx application using the Kubernetes command
line tool kubectl from the instructions in a manifest file (see Deploying a Sample
Nginx App on a Cluster Using Kubectl).
Also note that you must not change the auto-generated names of resources that Container
Engine for Kubernetes has created (such as the names of worker nodes).
1. In the Console, open the navigation menu. Under Solutions and Platform, go to
Developer Services and click Container Clusters.
2. Choose a Compartment you have permission to work in.
3. On the Cluster List page, click the name of the cluster you want to modify.
4. On the Cluster page, click the name of the node pool that you want to modify.
5. Use the Node Pool Details tab to view information about the node pool, including:
l The status of the node pool.
l The node pool's OCID.
l The configuration currently used when starting new worker nodes in the node
pool, including:
o the version of Kubernetes to run on worker nodes
o the shape to use for worker nodes
o the image to use on worker nodes
l The availability domains, and different regional subnets (recommended) or AD-
specific subnets hosting worker nodes.
6. (optional) Change properties of the node pool and worker nodes by clicking Edit and
specifying:
l Name: A different name for the node pool. Avoid entering confidential
information.
l Version: A different version of Kubernetes to run on new worker nodes in the
node pool when performing an in-place upgrade. The Kubernetes version on
worker nodes must be either the same version as that on the master nodes, or an
earlier version that is still compatible (see Kubernetes Versions and Container
Engine for Kubernetes). To start new worker nodes running the Kubernetes
version you specify, 'drain' existing worker nodes in the node pool (to prevent
new pods starting and to delete existing pods) and then terminate each of the
existing worker nodes in turn.
You can also specify a different version of Kubernetes to run on new worker nodes
by performing an out-of-place upgrade. For more information about upgrading
worker nodes, see Upgrading the Kubernetes Version on Worker Nodes in a
Cluster.
7. (optional) Change the number and placement of worker nodes in the node pool by
clicking Scale and specifying:
l the number of worker nodes you want in the node pool after the scale operation is
complete
l the availability domains in which to place the worker nodes
l the regional subnets (recommended) or AD-specific subnets to host the worker
nodes
8. Use the Nodes tab to see information about specific worker nodes in the node pool.
Optionally edit the configuration details of a specific worker node by clicking the worker
node's name.
l When you delete a cluster, no other resources created during the cluster creation
process or associated with the cluster (such as VCNs, internet gateways, NAT gateways,
route tables, security lists, load balancers, and block volumes) are deleted
automatically. If you want to delete these resources, you have to do so manually.
l Container Engine for Kubernetes creates the worker nodes (compute instances) in a
cluster with auto-generated names in the format oke-c<part-of-cluster-OCID>-
n<part-of-node-pool-OCID>-s<part-of-subnet-OCID>-<slot>. Do not change the
auto-generated names of worker nodes. If you do change the auto-generated name of a
worker node and then delete the cluster, the renamed worker node is not deleted. You
would have to delete the renamed worker node manually.
1. In the Console, open the navigation menu. Under Solutions and Platform, go to
Developer Services and click Container Clusters.
2. Choose a Compartment you have permission to work in.
3. On the Cluster List page, click the Delete icon beside the cluster to delete, and confirm
that you want to delete it.
You can also delete a cluster using the Delete Cluster button on the Cluster page.
Monitoring Clusters
Having created a cluster, you can monitor the overall status of the cluster itself, and the
nodes and node pools within it.
In addition to monitoring the overall status of clusters, node pools, and nodes, you can also
monitor their health, capacity, and performance at a more granular level using metrics,
alarms, and notifications. See Container Engine for Kubernetes Metrics.
1. In the Console, open the navigation menu. Under Solutions and Platform, go to
Developer Services and click Container Clusters.
2. Choose a Compartment you have permission to work in.
The Status column on the Cluster List page shows a summary status for each
individual cluster and its master nodes. Clusters can have one of the following statuses:
Note that the cluster's summary status is not necessarily directly related to the status of
node pools and nodes within the cluster.
3. On the Cluster List page, click the name of the cluster for which you want to see
detailed status.
4. Display the cluster's Metrics tab to see more granular information about the health,
capacity, and performance of the cluster. See Container Engine for Kubernetes Metrics.
5. Display the Node Pools tab to see the summary status of each node pool in the cluster.
6. On the Node Pools tab, click the name of a node pool for which you want to see
detailed status.
7. Display the node pool's Metrics tab to see more granular information about the health,
capacity, and performance of the node pool. See Container Engine for Kubernetes
Metrics.
8. Display the Nodes tab to see the summary status of each node in the node pool.
Nodes can have one of the following statuses:
Inactive Node still exists, but is Compute resource has a status of Stopped,
not running. Stopping, or Down For Maintenance.
9. Click View Metrics beside a node to see more granular information about the health,
capacity, and performance of that node. See Container Engine for Kubernetes Metrics.
Use the GetCluster and GetNodePool operations to monitor the status of Kubernetes clusters.
l You can monitor and manage operations performed on a particular cluster by Container
Engine for Kubernetes using the Work Requests tab of the cluster's Summary page.
l You can view all operations performed by Container Engine for Kubernetes as log events
using the Oracle Cloud Infrastructure Audit service.
Note that in addition to monitoring the operations performed by Container Engine for
Kubernetes as described in this topic, you can also monitor the health, capacity, and
performance of Kubernetes clusters themselves using metrics, alarms, and notifications. See
Container Engine for Kubernetes Metrics.
1. In the Console, open the navigation menu. Under Solutions and Platform, go to
Developer Services and click Container Clusters.
2. Choose a Compartment you have permission to work in.
3. On the Cluster List page, click the name of the cluster for which you want to monitor
and manage operations.
The Cluster page shows information about the cluster.
4. Display the Work Requests tab, showing the recent operations performed on the
cluster.
To view all operations performed by Container Engine for Kubernetes as log events:
1. In the Console, open the navigation menu. Under Governance and Administration,
go to Governance and click Audit.
2. Choose a Compartment you have permission to work in.
3. Search and filter to show the operations performed by Container Engine for Kubernetes.
See Viewing Audit Log Events.
Note that an Oracle Cloud Infrastructure CLI command in the kubeconfig file generates
authentication tokens that are short-lived, cluster-scoped, and specific to individual users. As
a result, you cannot share kubeconfig files between users to access Kubernetes clusters. The
generated authentication tokens are also unsuitable if you want other processes and tools to
access the cluster, such as continuous integration and continuous delivery (CI/CD) tools. In
this case, consider creating a Kubernetes service account and adding its associated
authentication token to the kubeconfig file. For more information, see Adding a Service
Account Authentication Token to a Kubeconfig File.
Note also that the version of kubectl you use must be compatible with the version of
Kubernetes running on clusters created by Container Engine for Kubernetes. In the case of
Cloud Shell, kubectl is regularly updated so it is always compatible with the versions of
Kubernetes currently supported by Container Engine for Kubernetes. In the case of a local
installation of kubectl, it is your responsibility to update kubectl regularly. For more
information about compatibility between different versions of kubernetes and kubectl, see the
Kubernetes documentation.
1. If you haven't already done so, follow the steps to set up the cluster's kubeconfig
configuration file for use in Cloud Shell, and (if necessary) set the KUBECONFIG
environment variable to point to the file. Note that you must set up your own kubeconfig
file. You cannot access a cluster using a kubeconfig file that a different user set up. See
Setting Up Cloud Shell Access to Clusters.
2. In the Cloud Shell window, enter kubectl followed by the command for the operation
you want to perform on the cluster. For a list of available commands and options, see
the kubectl documentation.
Note that you must have the appropriate permissions to run the command you enter.
See About Access Control and Container Engine for Kubernetes.
1. If you haven't already done so, install kubectl (see the kubectl documentation).
2. If you haven't already done so, follow the steps to set up the cluster's kubeconfig
configuration file for use locally, and (if necessary) set the KUBECONFIG environment
variable to point to the file. Note that you must set up your own kubeconfig file. You
cannot access a cluster using a kubeconfig file that a different user set up. See Setting
Up Local Access to Clusters.
3. In a local terminal window, enter kubectl followed by the command for the operation
you want to perform on the cluster. For a list of available commands and options, see
the kubectl documentation.
Note that you must have the appropriate permissions to run the command you enter.
See About Access Control and Container Engine for Kubernetes.
You use the Kubernetes Dashboard to get an overview of applications running on a cluster, as
well as to create or modify individual Kubernetes resources. The Kubernetes Dashboard also
reports the status of Kubernetes resources in the cluster, and any errors that have occurred.
In contrast to the Kubernetes Dashboard, Container Engine for Kubernetes enables you to
create and delete Kubernetes clusters and node pools, and to manage the associated
compute, network, and storage resources.
Before you can use the Kubernetes Dashboard to access a cluster, you need to specify the
cluster on which to perform operations by setting up the cluster's kubeconfig file.
Note that an Oracle Cloud Infrastructure CLI command in the kubeconfig file generates
authentication tokens that are short-lived, cluster-scoped, and specific to individual users. As
a result, you cannot share kubeconfig files between users to access Kubernetes clusters. The
generated authentication tokens are also unsuitable if you want other processes and tools to
access the cluster, such as continuous integration and continuous delivery (CI/CD) tools. In
this case, consider creating a Kubernetes service account and adding its associated
authentication token to the kubeconfig file. For more information, see Adding a Service
Account Authentication Token to a Kubeconfig File.
Note
1. If you haven't already done so, follow the steps to set up the cluster's kubeconfig
configuration file and (if necessary) set the KUBECONFIG environment variable to point
to the file. Note that you must set up your own kubeconfig file. You cannot access a
cluster using a kubeconfig file that a different user set up. See Setting Up Cluster
Access.
2. In a text editor, create a file (for example, called oke-admin-service-account.yaml)
with the following content:
apiVersion: v1
kind: ServiceAccount
metadata:
name: oke-admin
namespace: kube-system
---
apiVersion: rbac.authorization.k8s.io/v1beta1
kind: ClusterRoleBinding
metadata:
name: oke-admin
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: cluster-admin
subjects:
- kind: ServiceAccount
name: oke-admin
namespace: kube-system
The file defines an administrator service account and a clusterrolebinding, both called
oke-admin.
3. Create the service account and the clusterrolebinding in the cluster by entering:
$ kubectl apply -f <filename>
where <filename> is the name of the file you created earlier. For example:
$ kubectl apply -f oke-admin-service-account.yaml
The output from the above command confirms the creation of the service account and
the clusterrolebinding:
serviceaccount "oke-admin" created
clusterrolebinding.rbac.authorization.k8s.io "oke-admin" created
You can now use the oke-admin service account to view and control the cluster, and to
connect to the Kubernetes dashboard.
4. Obtain an authentication token for the oke-admin service account by entering:
$ kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep oke-admin |
awk '{print $1}')
The output from the above command includes an authentication token (a long
alphanumeric string) as the value of the token: element, as shown below:
Name: oke-admin-token-gwbp2
Namespace: kube-system
Labels: <none>
Annotations: kubernetes.io/service-account.name: oke-admin
kubernetes.io/service-account.uid: 3a7fcd8e-e123-11e9-81ca-0a580aed8570
Type: kubernetes.io/service-account-token
Data
====
ca.crt: 1289 bytes
namespace: 11 bytes
token: eyJh______px1Q
However, the generated authentication token is not appropriate to authenticate processes and
tools accessing the cluster, such as continuous integration and continuous delivery (CI/CD)
tools. To ensure access to the cluster, such tools require long-lived, non-user-specific
authentication tokens.
One solution is to use a Kubernetes service account, as described in this topic. A service
account has an associated service account authentication token, which is stored as a
Kubernetes secret. Having created a service account, you bind it to a clusterrolebinding that
has cluster administration permissions. You can then add the service account (and its service
account authentication token) as a user definition in the kubeconfig file itself. Other tools can
then use the service account authentication token when accessing the cluster.
Note that to run the commands in this topic, you must have the appropriate permissions. See
About Access Control and Container Engine for Kubernetes.
1. If you haven't already done so, follow the steps to set up the cluster's kubeconfig
configuration file and (if necessary) set the KUBECONFIG environment variable to point
to the file. Note that you must set up your own kubeconfig file. You cannot access a
cluster using a kubeconfig file that a different user set up. See Setting Up Cluster
Access.
2. In a terminal window, create a new service account in the kube-system namespace by
entering the following kubectl command:
$ kubectl -n kube-system create serviceaccount <service-account-name>
The output from the above command confirms the creation of the service account. For
example:
serviceaccount/kubeconfig-sa created
Note that creating the service account in the kube-system namespace is recommended
good practice, and is assumed in the instructions in this topic. However, if you prefer,
you can create the service account in another namespace to which you have access.
3. Create a new clusterrolebinding with cluster administration permissions and bind it to
the service account you just created by entering the following kubectl command:
$ kubectl create clusterrolebinding <binding-name> --clusterrole=cluster-admin --
serviceaccount=kube-system:<service-account-name>
The output from the above command confirms the creation of the clusterrolebinding.
For example:
clusterrolebinding.rbac.authorization.k8s.io/add-on-cluster-admin created
4. Obtain the name of the service account authentication token and assign its value to an
For example:
$ TOKENNAME=`kubectl -n kube-system get serviceaccount/kubeconfig-sa -o jsonpath='{.secrets
[0].name}'`
5. Obtain the value of the service account authentication token and assign its value
(decoded from base64) to an environment variable. These instructions assume you
specify TOKEN as the name of the environment variable. The commands to enter
depend on the operating system:
l To obtain the value of the service account authentication token in a MacOS, Linux,
or Unix environment, enter the following command:
$ TOKEN=`kubectl -n kube-system get secret $TOKENNAME -o jsonpath='{.data.token}'| base64
--decode`
b. Copy the output from the above command and paste it into a base64
decoder (for example, https://www.base64decode.org,
https://www.base64decode.net, or similar).
c. Copy the output from the base64 decoder.
d. Enter the following command:
$ TOKEN=`[<base64-decoded-output>]`
The service account (and its authentication token) is added to the list of users defined in
the kubeconfig file.
For example, to add the kubeconfig-sa service account and its authentication token to
the kubeconfig file, enter:
$ kubectl config set-credentials kubeconfig-sa --token=$TOKEN
The output from the above command confirms the service account has been added to
the kubeconfig file. For example:
User "kubeconfig-sa" set.
7. Set the user specified in the kubeconfig file for the current context to be the new service
account user you created, by entering the following kubectl command:
$ kubectl config set-context --current --user=<service-account-name>
For example:
$ kubectl config set-context --current --user=kubeconfig-sa
The output from the above command confirms the current context has been changed.
For example:
Context "context-ctdiztdhezd" modified.
The output from the above command shows the pods running on the cluster. If the
command runs successfully, the service account user in the kubeconfig file has been
successfully authenticated using the service account authentication token.
9. Distribute the kubeconfig file as necessary to enable other processes and tools (such as
continuous integration and continuous delivery (CI/CD) tools) to access the cluster.
Note
1. If you haven't already done so, follow the steps to set up the cluster's kubeconfig
configuration file and (if necessary) set the KUBECONFIG environment variable to point
to the file. Note that you must set up your own kubeconfig file. You cannot access a
cluster using a kubeconfig file that a different user set up. See Setting Up Cluster
Access.
2. In a terminal window, deploy the sample Nginx application by entering kubectl create
-f https://k8s.io/examples/application/deployment.yaml
Tip
3. Use the Kubernetes Dashboard or kubectl to confirm that the sample application has
deployed successfully. For example:
a. Enter kubectl proxy to start the Kubernetes Dashboard.
b. Open a browser and go to http://localhost:8001/api/v1/namespaces/kube-
system/services/https:kubernetes-dashboard:/proxy/ to display the
Kubernetes Dashboard.
c. Click Overview to see the applications deployed on the cluster.
You can see the Nginx sample application has been deployed as two pods, on two nodes in the
cluster.
If you want the application to pull images that reside in Oracle Cloud Infrastructure Registry,
you have to perform two steps:
l You have to use kubectl to create a Docker registry secret. The secret contains the
Oracle Cloud Infrastructure credentials to use when pulling the image. When creating
secrets, Oracle strongly recommends you use the latest version of kubectl (see the
kubectl documentation).
l You have to specify the image to pull from Oracle Cloud Infrastructure Registry,
including the repository location and the Docker registry secret to use, in the
application's manifest file.
1. If you haven't already done so, follow the steps to set up the cluster's kubeconfig
configuration file and (if necessary) set the KUBECONFIG environment variable to point
to the file. Note that you must set up your own kubeconfig file. You cannot access a
cluster using a kubeconfig file that a different user set up. See Setting Up Cluster
Access.
2. In a terminal window, enter:
$ kubectl create secret docker-registry <secret-name> --docker-server=<region-key>.ocir.io --
docker-username='<tenancy-namespace>/<oci-username>' --docker-password='<oci-auth-token>' --
docker-email='<email-address>'
where:
l <secret-name> is a name of your choice, that you will use in the manifest file to
refer to the secret . For example, ocirsecret
l <region-key> is the key for the Oracle Cloud Infrastructure Registry region
you're using. For example, iad. See Availability by Region.
l ocir.io is the Oracle Cloud Infrastructure Registry name.
l <tenancy-namespace> is the auto-generated Object Storage namespace string of
the tenancy containing the repository from which the application is to pull the
image (as shown on the Tenancy Information page). For example, the
namespace of the acme-dev tenancy might be ansh81vru1zp. Note that for some
older tenancies, the namespace string might be the same as the tenancy name in
all lower-case letters (for example, acme-dev).
l <oci-username> is the username to use when pulling the image. The username
must have access to the tenancy specified by <tenancy-name>. For example,
[email protected] . If your tenancy is federated with Oracle Identity Cloud Service,
use the format oracleidentitycloudservice/<username>
l <oci-auth-token> is the auth token of the user specified by <oci-username>.
For example, k]j64r{1sJSSF-;)K8
l <email-address> is an email address. An email address is required, but it
doesn't matter what you specify. For example, [email protected]
Note the use of single quotes around strings containing special characters.
For example, combining the previous examples, you might enter:
$ kubectl create secret docker-registry ocirsecret --docker-server=phx.ocir.io --docker-
username='ansh81vru1zp/[email protected]' --docker-password='k]j64r{1sJSSF-;)K8' --docker-
email='[email protected]'
Having created the Docker secret, you can now refer to it in the application manifest
file.
To specify the image to pull from Oracle Cloud Infrastructure Registry, along with the Docker
secret to use, during deployment of an application to a cluster:
Here's an example of what the manifest might look like when you've added the
containers and imagePullSecrets sections:
apiVersion: v1
kind: Pod
metadata:
name: ngnix-image
spec:
containers:
- name: ngnix
image: phx.ocir.io/ansh81vru1zp/project01/ngnix-lb:latest
imagePullPolicy: Always
ports:
- name: nginx
containerPort: 8080
protocol: TCP
imagePullSecrets:
- name: ocirsecret
For additional security, when you create a new cluster you can specify that Kubernetes
secrets at rest in etcd are to be encrypted using the Oracle Cloud Infrastructure Vault service
(see Overview of Vault). Before you can create a cluster where Kubernetes secrets are
encrypted in the etcd key-value store, you have to:
l know the name and OCID of a suitable master encryption key in Vault
l create a dynamic group that includes all clusters in the compartment in which you are
going to create the new cluster
l create a policy authorizing the dynamic group to use the master encryption key
Having created the cluster and specified that you want Kubernetes secrets at rest in the etcd
key-value store to be encrypted, you can optionally restrict the use of the master encryption
key by modifying the dynamic group to include just that cluster.
l You can only select the option to encrypt the Kubernetes secrets in the cluster's etcd
key-value store when creating a new 'custom cluster'. You cannot encrypt Kubernetes
secrets in the etcd key-value stores of existing 'custom clusters', or in the etcd key-
value stores of 'quick clusters'.
l You can only select the option to encrypt Kubernetes secrets in the cluster's etcd key-
value store if you specify Kubernetes version 1.13.x or later as the version of
Kubernetes to run on the master nodes of the cluster.
l Policies must have been defined to authorize Container Engine for Kubernetes to use the
master encryption key, and to authorize users to delegate key usage to Container
Engine for Kubernetes in the first place. For more information, see Let a user group
delegate key usage in a compartment and Let Block Volume, Object Storage, File
Storage, and Container Engine for Kubernetes services encrypt and decrypt volumes,
buckets, file systems, and Kubernetes secrets in Common Policies.
l After you've specified a master encryption key for a new cluster and created the
cluster, do not subsequently delete the master encryption key in the Vault service. As
soon as you schedule a key for deletion in Vault, the Kubernetes secrets stored for the
cluster in etcd become inaccessible. If you have already scheduled the key for deletion,
it might still be in the Pending Deletion state. If that is the case, cancel the scheduled
key deletion (see To cancel the deletion of a key) to restore access to the Kubernetes
secrets. If you allow the scheduled key deletion operation to complete and the master
encryption key to be deleted, the Kubernetes secrets stored for the cluster in etcd are
permanently inaccessible. As a result, cluster upgrades will fail. In this situation, you
have no choice but to delete and recreate the cluster.
Having created a dynamic group that includes all clusters in the compartment, you can
now create a policy to give the dynamic group access to the master encryption key in
Vault.
4. Create a new policy to enable use of the master encryption key:
a. Open the navigation menu. Under Governance and Administration, go to
Identity and click Policies.
b. Follow the instructions in To create a policy, and give the policy a name (for
example, acme-oke-kms-dyn-grp-policy).
c. Enter a policy statement to give the dynamic group access to the master
encryption key, in the format:
Allow dynamic-group <dynamic-group-name> to use keys in compartment <compartment-name>
where target.key.id = '<key-OCID>'
where:
l <dynamic-group-name> is the name of the dynamic group you created
earlier.
l <compartment-name> is the name of the compartment containing the
master encryption key.
l <key-OCID> is the OCID of the master encryption key in Vault.
For example:
Allow dynamic-group <acme-oke-kms-dyn-grp> to use keys in compartment acme-kms-key-
compartment where target.key.id = 'ocid1.key.oc1.iad.annrl______trfg'
Note the following instructions assume the UNIX machine you use to connect to the worker
node:
How to connect to worker nodes using SSH depends on whether you specified public or private
subnets for the worker nodes when defining the node pools in the cluster.
To connect to a worker node in a public subnet through SSH from a UNIX machine using the
ssh utility:
1. Find out the IP address of the worker node to which you want to connect. You can do this
in a number of ways:
l Using kubectl. If you haven't already done so, follow the steps to set up the
cluster's kubeconfig configuration file and (if necessary) set the KUBECONFIG
environment variable to point to the file. Note that you must set up your own
kubeconfig file. You cannot access a cluster using a kubeconfig file that a different
user set up. See Setting Up Cluster Access. Then in a terminal window, enter
kubectl get nodes to see the public IP addresses of worker nodes in node pools
in the cluster.
l Using the Console. In the Console, display the Cluster List page and then select
the cluster to which the worker node belongs. On the Node Pools tab, click the
name of the node pool to which the worker node belongs. On the Nodes tab, you
see the public IP address of every worker node in the node pool.
l Using the REST API. Use the ListNodePools operation to see the public IP
addresses of worker nodes in a node pool.
2. In the terminal window, enter ssh opc@<node_ip_address> to connect to the worker
node, where <node_ip_address> is the IP address of the worker node that you made a
note of earlier. For example, you might enter ssh [email protected].
Note that if the SSH private key is not stored in the file or in the path that the ssh utility
expects (for example, the ssh utility might expect the private key to be stored in
~/.ssh/id_rsa), you must explicitly specify the private key filename and location in one
of two ways:
l Use the -i option to specify the filename and location of the private key. For
example, ssh -i ~/.ssh/my_keys/my_host_key_filename [email protected]
l Add the private key filename and location to an SSH configuration file, either the
client configuration file (~/.ssh/config) if it exists, or the system-wide client
configuration file (/etc/ssh/ssh_config). For example, you might add the
following:
Host 192.0.2.254 IdentityFile ~/.ssh/my_keys/my_host_key_filename
For more about the ssh utility’s configuration file, enter man ssh_config
Note also that permissions on the private key file must allow you read/write/execute
access, but prevent other users from accessing the file. For example, to set appropriate
permissions, you might enter chmod 600 ~/.ssh/my_keys/my_host_key_filename. If
permissions are not set correctly and the private key file is accessible to other users,
the ssh utility will simply ignore the private key file.
from the internet. For more information about bastion hosts, see the white paper Bastion
Hosts: Protected Access for Virtual Cloud Networks.
You can also use pod security policies to provide default values for pods, by 'mutating' the
pod.
Having defined a pod security policy for a cluster, you have to authorize the requesting user
or target pod's service account to use the policy. You do this by creating a role (or clusterrole)
to access the pod security policy, and then creating a rolebinding (or clusterrolebinding)
between the role (or clusterrole) and the requesting user or target pod's service account. For
more information about roles, clusterroles, and bindings, see About Access Control and
Container Engine for Kubernetes.
You specify whether a cluster enforces the pod security policies defined for it by enabling the
cluster's PodSecurityPolicy admission controller. The PodSecurityPolicy admission controller
acts on creation and modification of a pod and determines if the pod should be admitted to the
cluster based on the requested security context in the pod spec and the cluster's pod security
policies. If multiple pod security policies exist, the PodSecurityPolicy admission controller
first compares the pod against non-mutating policies in alphabetical order and uses the first
policy that successfully validates the pod. If no non-mutating pods validate the pod, the
PodSecurityPolicy admission controller compares the pod against mutating policies in
alphabetical order and uses the first policy that successfully validates the pod.
Warning
Warning 1:
Warning 2:
Clusters you create with Container Engine for Kubernetes automatically include a pod security
policy, a clusterrole, and a clusterrolebinding that allow any pod in the kube-system
namespace to run. When you enable a cluster's PodSecurityPolicy admission controller, this
pod security policy (and the associated clusterrole and clusterrolebinding) enable the
Kubernetes system pods to run. The pod security policy, clusterrole, and clusterrolebinding
are defined in the kube-system.yaml file (see kube-system.yaml Reference).
Note that you can create pod security policies for a cluster before enabling the cluster's
PodSecurityPolicy admission controller. Also note that you can disable a cluster's
PodSecurityPolicy admission controller that was previously enabled. In this case, any
previously created pod security policies, roles (or clusterroles), and rolebindings (or
clusterrolebindings) are not deleted. The pod security policies are simply not enforced. Any
application pod will be able to run on the cluster.
For more information about pod security policies and the PodSecurityPolicy admission
controller, see the Kubernetes documentation.
name: acme-app-psp
spec:
privileged: false # Don't allow privileged pods!
# The rest fills in some required fields.
seLinux:
rule: RunAsAny
supplementalGroups:
rule: RunAsAny
runAsUser:
rule: RunAsAny
fsGroup:
rule: RunAsAny
volumes:
- '*'
For example:
kubectl create -f acme-app-psp.yaml
2. Create the role (or clusterrole) to access the pod security policy:
a. Define and save a role (or clusterrole) in a file. For example, in acme-app-psp-
crole.yaml.
For example:
# Cluster role which grants access to the app pod security policy
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: acme-app-psp-crole
rules:
- apiGroups:
- policy
resourceNames:
- acme-app-psp
resources:
- podsecuritypolicies
verbs:
- use
For example:
kubectl create -f acme-app-psp-crole.yaml
3. Create the rolebinding (or clusterrolebinding) to authorize the application pods to use
the pod security policy:
a. Define and save the rolebinding (or clusterrolebinding) in a file. For example, in
acme-app-psp-crole-bind.yaml.
For example:
# Role binding which grants access to the app pod security policy
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: acme-app-psp-binding
namespace: acme-namespace
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: acme-app-psp-crole
subjects:
# For all service accounts in acme-namespace
- apiGroup: rbac.authorization.k8s.io
kind: Group
name: system:serviceaccounts:acme-namespace
For example:
kubectl create -f acme-app-psp-crole-bind.yaml
Having defined a pod security policy and authorized application pods to use it by creating a
role and rolebinding (or a clusterrole and clusterrolebinding), enable the cluster's
PodSecurityPolicy admission controller to enforce the pod security policy (if it's not enabled
already).
To enable the PodSecurityPolicy admission controller in existing clusters using the Console:
1. Follow the instructions in Creating a Pod Security Policy for Application Pods to create
pod security policies for the PodSecurityPolicy admission controller to enforce when
accepting pods into the existing cluster.
We strongly recommend you first verify the pod security policies in a development or
test environment. That way, you can be sure the pod security policies work as you
expect and correctly allow (or refuse) pods to start on the cluster.
2. In the Console, open the navigation menu. Under Solutions and Platform, go to
Developer Services and click Container Clusters.
3. Choose a Compartment you have permission to work in.
4. On the Cluster List page, click the name of the cluster you want to modify.
5. On the Cluster Details tab, click Not Enforced beside Pod Security Policies.
6. In the Pod Security Policies window, select Enforced.
From now on, no new application pods will be accepted into the cluster unless suitable
pod security policies exist, along with roles (or clusterroles) and rolebindings (or
clusterrolebindings) to associate pods with policies. Note that any currently running
pods will continue to run regardless.
7. Click Save Changes.
kube-system.yaml Reference
The pod security policy (and the clusterrole and clusterrolebinding) for Kubernetes system
privileged pods are automatically created when you create a new cluster. These allow any pod
in the kube-system namespace to run. They are created from definitions in the kube-
system.yaml shown below:
apiVersion: policy/v1beta1
kind: PodSecurityPolicy
metadata:
annotations:
# See https://kubernetes.io/docs/concepts/policy/pod-security-policy/#seccomp
seccomp.security.alpha.kubernetes.io/allowedProfileNames: '*'
name: oke-privileged
spec:
allowedCapabilities:
- '*'
allowPrivilegeEscalation: true
fsGroup:
rule: 'RunAsAny'
hostIPC: true
hostNetwork: true
hostPID: true
hostPorts:
- min: 0
max: 65535
privileged: true
readOnlyRootFilesystem: false
runAsUser:
rule: 'RunAsAny'
seLinux:
rule: 'RunAsAny'
supplementalGroups:
rule: 'RunAsAny'
volumes:
- '*'
---
# Cluster role which grants access to the privileged pod security policy
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: oke-privileged-psp
rules:
- apiGroups:
- policy
resourceNames:
- oke-privileged
resources:
- podsecuritypolicies
verbs:
- use
---
# Role binding for kube-system - allow kube-system service accounts - should take care of CNI i.e.
flannel running in the kube-system namespace
# Assumes access to the kube-system is restricted
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: kube-system-psp
namespace: kube-system
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: privileged-psp
subjects:
# For all service accounts in the kube-system namespace
- apiGroup: rbac.authorization.k8s.io
kind: Group
name: system:serviceaccounts:kube-system
For most operations on Kubernetes clusters created and managed by Container Engine for
Kubernetes, Oracle Cloud Infrastructure Identity and Access Management (IAM) provides
access control. A user's permissions to access clusters comes from the groups to which they
belong. The permissions for a group are defined by policies. Policies define what actions
members of a group can perform, and in which compartments. Users can then access clusters
and perform operations based on the policies set for the groups they are members of.
In addition to IAM, the Kubernetes RBAC Authorizer can enforce additional fine-grained access
control for users on specific clusters via Kubernetes RBAC roles and clusterroles. A
Kubernetes RBAC role is a collection of permissions. For example, a role might include read
permission on pods and list permission for pods. A Kubernetes RBAC clusterrole is just like a
role, but can be used anywhere in the cluster. A Kubernetes RBAC rolebinding maps a role to a
user or set of users, granting that role's permissions to those users for resources in that
namespace. Similarly, a Kubernetes RBAC clusterrolebinding maps a clusterrole to a user or
set of users, granting that clusterrole's permissions to those users across the entire cluster.
IAM and the Kubernetes RBAC Authorizer work together to enable users who have been
successfully authorized by at least one of them to complete the requested Kubernetes
operation.
When a user attempts to perform any operation on a cluster (except for create role and create
clusterrole operations), IAM first determines whether the group to which the user belongs has
the appropriate and sufficient permissions. If so, the operation succeeds. If the attempted
operation also requires additional permissions granted via a Kubernetes RBAC role or
clusterrole, the Kubernetes RBAC Authorizer then determines whether the user has been
granted the appropriate Kubernetes role or clusterrole.
Typically, you’ll want to define your own Kubernetes RBAC roles and clusterroles when
deploying a Kubernetes cluster to provide additional fine-grained control. When you attempt
to perform a create role or create clusterrole operation, the Kubernetes RBAC Authorizer first
determines whether you have sufficient Kubernetes privileges. To create a role or clusterrole,
you must have been assigned an existing Kubernetes RBAC role (or clusterrole) that has at
least the same or higher privileges as the new role (or clusterrole) you’re attempting to
create.
By default, users are not assigned any Kubernetes RBAC roles (or clusterroles) by default. So
before attempting to create a new role (or clusterrole), you must be assigned an
appropriately privileged role (or clusterrole). A number of such roles and clusterroles are
always created by default, including the cluster-admin clusterrole (for a full list, see Default
Roles and Role Bindings in the Kubernetes documentation). The cluster-admin clusterrole
essentially confers super-user privileges. A user granted the cluster-admin clusterrole can
perform any operation across all namespaces in a given cluster.
Note that Oracle Cloud Infrastructure tenancy administrators already have sufficient
privileges, and do not require the cluster-admin clusterrole.
Note
Follow these steps to grant a user who is not a tenancy administrator the Kubernetes RBAC
cluster-admin clusterrole on a cluster deployed on Oracle Cloud Infrastructure:
1. If you haven't already done so, follow the steps to set up the cluster's kubeconfig
configuration file and (if necessary) set the KUBECONFIG environment variable to point
to the file. Note that you must set up your own kubeconfig file. You cannot access a
cluster using a kubeconfig file that a different user set up. See Setting Up Cluster
Access.
2. In a terminal window, grant the Kubernetes RBAC cluster-admin clusterrole to the user
by entering:
$ kubectl create clusterrolebinding <my-cluster-admin-binding> --clusterrole=cluster-admin --
user=<user_OCID>
where:
l <my-cluster-admin-binding> is a string of your choice to be used as the name
for the binding between the user and the Kubernetes RBAC cluster-admin
clusterrole. For example, jdoe_clst_adm
l <user_OCID> is the user's OCID (obtained from the Console ). For example,
ocid1.user.oc1..aaaaa...zutq (abbreviated for readability).
For example:
$ kubectl create clusterrolebinding jdoe_clst_adm --clusterrole=cluster-admin --
user=ocid1.user.oc1..aaaaa...zutq
Example: Giving a developer user the ability to read pods in a new cluster
Note
Follow these steps to give a developer the necessary Oracle Cloud Infrastructure and
Kubernetes RBAC permissions to use kubectl to view pods running on a cluster deployed on
Oracle Cloud Infrastructure:
1. Create a new Oracle Cloud Infrastructure user for the developer to use (for example,
called [email protected]), and make a note of the new user's OCID (for example,
ocid1.user.oc1..aaaaa...tx5a, abbreviated for readability). See To create a user.
2. Create a new Oracle Cloud Infrastructure group and add the new user to the group (for
example, called acme-dev-pod-vwr). See To create a group.
3. Create a new Oracle Cloud Infrastructure policy that grants the new group the
CLUSTER_USE permission on clusters, with a policy statement like:
Allow group acme-dev-pod-vwr to use clusters in <location>
In the above policy statement, replace <location> with either tenancy (if you are
creating the policy in the tenancy's root compartment) or compartment <compartment-
name> (if you are creating the policy in an individual compartment).
See To create a policy.
4. Create a new cluster in the Console. See Creating a Kubernetes Cluster.
5. Follow the steps to set up the cluster's kubeconfig configuration file and (if
necessary) set the KUBECONFIG environment variable to point to the file. Note that you
must set up your own kubeconfig file. You cannot access a cluster using a kubeconfig
file that a different user set up. See Setting Up Cluster Access.
6. In a text editor, create a file (for example, called role-pod-reader.yaml) with the
following content. This file defines a Kubernetes RBAC role that enables users to read
pod details.
kind: Role
apiVersion: rbac.authorization.k8s.io/v1
metadata:
namespace: default
name: pod-reader
rules:
- apiGroups: [""] # "" indicates the core API group
resources: ["pods"]
verbs: ["get", "watch", "list"]
7. In a terminal window, create the new role in the cluster using kubectl. For example, if
you gave the yaml file that defines the new role the name role-pod-reader.yaml, enter
the following:
$ kubectl create -f role-pod-reader.yaml
8. In a terminal window, bind the Kubernetes RBAC role you just created to the Oracle
Cloud Infrastructure user account you created earlier by entering the following to create
a new rolebinding (in this case, called pod-reader-binding):
$ kubectl create rolebinding pod-reader-binding --role=pod-reader --
user=ocid1.user.oc1..aaaaa...tx5a
9. Give the developer the credentials of the new Oracle Cloud Infrastructure user you
created earlier, and tell the developer they can now see details of pods running on the
cluster deployed on Oracle Cloud Infrastructure by:
l Signing in to the Console using the new user's credentials.
l Following the instructions in Setting Up Cluster Access to set up their own copy of
the cluster's kubeconfig file. If the file does not have the expected default name
and location of $HOME/.kube/config, the developer will also have to set the
KUBECONFIG environment variable to point to the file. Note that the developer
must set up their own kubeconfig file. They cannot access a cluster using a
kubeconfig file that you (or a different user) set up.
l Using kubectl to see details of the pods by entering:
$ kubectl get pods
l The operating system image to use for worker nodes. The image is a template of a
virtual hard drive that determines the operating system and other software for the
worker node.
l The shape to use for worker nodes. The shape is the number of CPUs and the amount of
memory to allocate to each newly created compute instance to be used as a worker
node.
This topic includes information about the images and shapes provided by Oracle Cloud
Infrastructure that are supported by Container Engine for Kubernetes for use in node pools.
Note that some of the shapes might not be available in your particular tenancy.
To see a list of the supported images and the shapes available in your tenancy, use the oci
ce node-pool-options get --node-pool-option-id all CLI command.
Supported Images
Container Engine for Kubernetes supports the provisioning of worker nodes using some, but
not all, of the latest Oracle Linux images provided by Oracle Cloud Infrastructure.
l When using the Console to create a 'custom cluster', view the list of values in the
Image drop-down menu to see the list of supported images.
l When using the CLI, use the command oci ce node-pool-options get --node-
pool-option-id all to see the supported images (in the data: sources: section of
the response).
Custom Images
When specifying the image that Container Engine for Kubernetes uses to provision worker
nodes in a node pool, you can specify your own custom image rather than one of the explicitly
supported Oracle Linux images returned by the oci ce node-pool-options get --node-
pool-option-id all command. Worker nodes provisioned from a custom image include the
customizations, configuration, and software that were present when the image was created.
Note that Container Engine for Kubernetes only supports custom images that are based on one
of the Oracle Linux images returned by the oci ce node-pool-options get command.
To provision worker nodes from a custom image, you must use the CLI or API and specify the
custom image’s OCID when creating the node pool. For example, by running the oci ce
node-pool create command and using the --node-image-id parameter to specify a custom
image's OCID, as follows:
oci ce node-pool create \
--cluster-id ocid1.cluster.oc1.iad.aaaaaaaaaf______jrd \
--name my-custom-linux-image \
--node-image-id ocid1.image.oc1.iad.aaaaaaaa6______nha \
--compartment-id ocid1.compartment.oc1..aaaaaaaay______t6q \
--kubernetes-version v1.15.7 \
--node-shape VM.Standard2.1 \
--placement-configs "[ { \"availabilityDomain\": \"nFuS:US-ASHBURN-AD-1\", \"subnetId\":
\"ocid1.subnet.oc1.iad.aaaaaaaa3______a6q\" } ]" \
--size 1 \
--region=us-ashburn-1
l Container Engine for Kubernetes installs Kubernetes on top of a custom image, and
Kubernetes or the installation software might change certain kernel configurations.
l Custom images must have access to a yum repository (public or internal).
l Custom images must not use a customized cloud-init. You can perform post-
provisioning customization using SSH or Daemonset.
l For the best support, ensure you create a custom image from the most up-to-date base
image.
For more information about custom images and Oracle Cloud Infrastructure, see Managing
Custom Images.
Supported shapes
Container Engine for Kubernetes supports the provisioning of worker nodes using many, but
not all, of the shapes provided by Oracle Cloud Infrastructure. More specifically:
l Supported: Bare Metal shapes, including standard shapes; HPC shapes, except in
RDMA networks; VM shapes, including standard shapes (except VM.Standard.E3.Flex).
l Not Supported: Dense I/O shapes; dedicated VM host shapes; GPU shapes on VMs and
Bare Metal instances; Micro VM shapes; HPC shapes on Bare Metal instances in
RDMA networks; VM.Standard.E3.Flex.
Note that you might be unable to select some shapes in your particular tenancy due to service
limits and compartment quotas, even though those shapes are supported by Container Engine
for Kubernetes.
To see the shapes that are supported by Container Engine for Kubernetes and available in your
tenancy:
l When using the Console to create a 'custom cluster', view the list of values in the Shape
drop-down menu to see the list of supported shapes.
l When using the CLI, use the command oci ce node-pool-options get --node-
pool-option-id all to see the supported shapes (in the data: shapes: section of the
response) that are available.
You might be able to use the Compute service's Console pages (or the Compute service's CLI
or API) to subsequently change the shape of a worker node after it has been created.
However, bear in mind that Container Engine for Kubernetes only supports those shapes
shown in the Shape drop-down menu or returned by the oci ce node-pool-options get --
node-pool-option-id all command.
For more information about all the shapes provided by Oracle Cloud Infrastructure, see
Compute Shapes.
MutatingAdmissionWebhook MutatingAdmissionWebhook
PersistentVolumeClaimResiz
e
ValidatingAdmissionWebhook MutatingAdmissionWebhook
ValidatingAdmissionWebhoo
k
NodeRestriction RuntimeClass
StorageObjectInUseProtectio
n
PodSecurityPolicy (optional,
see Using Pod Security
Polices with Container Engine
for Kubernetes)
RuntimeClass No No Yes
The version of Kubernetes that you specify for the worker nodes in a node pool must be either
the same Kubernetes version as that running on the master nodes, or an earlier Kubernetes
version that is still compatible. In other words:
l The master nodes in a new cluster must run the same version of Kubernetes as the
version running on worker nodes, or must be no more than two versions ahead.
l The worker nodes in a node pool must not run a more recent version of Kubernetes than
the associated master nodes.
Kubernetes version numbers have the format x.y.z where x is a major release, y is a minor
release, and z is a patch release. For example, 1.15.7.
Kubernetes itself is supported for three minor versions at a time (the current release version
and two previous versions).
l The Kubernetes version on worker nodes can lag behind the version on the master
nodes by up to two versions, but no more. If the version on the worker nodes is more
than two versions behind the version on the master nodes, the Kubernetes versions on
the worker nodes and the master nodes are incompatible.
l The Kubernetes version on worker nodes must never be more recent than the version
on the master nodes.
For the Kubernetes versions currently and previously supported by Container Engine for
Kubernetes, see Supported Versions of Kubernetes.
Notes about Container Engine for Kubernetes Support for Kubernetes Version 1.16
l A number of versions of the following Kubernetes APIs, in favor of more stable versions
(as described in this kubernetes.io blog post):
o NetworkPolicy
o PodSecurityPolicy
o DaemonSet
o Deployment
o StatefulSet
o ReplicaSet
If a deprecated API version is used, workloads running on Kubernetes version 1.16
clusters are subject to disruption.
l Any labels in the k8s.io and kubernetes.io namespaces, except for the labels listed
here. If a disallowed label is used, errors occur when creating or updating node pools in
Kubernetes version 1.16 clusters.
Before upgrading clusters to Kubernetes version 1.16, Oracle strongly recommends you
prepare as follows:
l Migrate to the stable API versions as soon as possible. Container Engine for Kubernetes
already supports Kubernetes versions that support the stable API versions, so you can
do this immediately. Depending on your use of the Kubernetes APIs, your migration
tasks might include:
o changing manifest files to reference the stable API versions
o updating custom integrations and controllers to call the stable API versions
o updating third party tools (ingress controllers, continuous delivery systems) to
call stable API versions
o verifying your version of kubectl adheres to the Kubernetes version skew support
policy described in the Kubernetes documentation
o making sure any references to documented Kubernetes examples are using stable
API versions
l Update the Kubernetes labels in the k8s.io and kubernetes.io namespaces to just those
listed here.
The master nodes and worker nodes that comprise the cluster can run different versions of
Kubernetes , provided you follow the Kubernetes version skew support policy described in the
Kubernetes documentation.
l You upgrade master nodes by upgrading the cluster and specifying a more recent
Kubernetes version for the cluster. Master nodes running older versions of Kubernetes
are upgraded. Because Container Engine for Kubernetes distributes the Kubernetes
Control Plane on multiple Oracle-managed master nodes to ensure high availability
(distributed across different availability domains in a region where supported), you're
able to upgrade the Kubernetes version running on master nodes with zero downtime.
Having upgraded master nodes to a new version of Kubernetes, you can subsequently
create new node pools with worker nodes running the newer version. Alternatively, you
can continue to create new node pools with worker nodes running older versions of
Kubernetes (providing those older versions are compatible with the Kubernetes version
running on the master nodes).
For more information about master node upgrade, see Upgrading the Kubernetes
Version on Master Nodes in a Cluster.
l You upgrade worker nodes in one of two ways:
o By performing an 'in-place' upgrade of a node pool in the cluster, specifying a
more recent Kubernetes version for the existing node pool.
o By performing an 'out-of-place' upgrade of a node pool in the cluster, replacing
the original node pool with a new node pool for which you've specified a more
recent Kubernetes version.
For more information about worker node upgrade, see Upgrading the Kubernetes
Version on Worker Nodes in a Cluster.
To find out more about the Kubernetes versions currently and previously supported by
Container Engine for Kubernetes, see Supported Versions of Kubernetes.
l Container Engine for Kubernetes only upgrades the Kubernetes version running on
master nodes when you explicitly initiate the upgrade operation.
l After upgrading master nodes to a newer version of Kubernetes, you cannot downgrade
the master nodes to an earlier Kubernetes version.
l Before you upgrade the version of Kubernetes running on the master nodes, it is your
responsibility to test that applications deployed on the cluster are compatible with the
new Kubernetes version. For example, before upgrading the existing cluster, you might
create a new separate cluster with the new Kubernetes version to test your applications.
l The versions of Kubernetes running on the master nodes and the worker nodes must be
compatible (that is, the Kubernetes version on the master nodes must be no more than
two minor versions ahead of the Kubernetes version on the worker nodes). See the
Kubernetes version skew support policy described in the Kubernetes documentation.
l If the version of Kubernetes currently running on the master nodes is more than one
version behind the most recent supported version, you are given a choice of versions to
upgrade to. If you want to upgrade to a version of Kubernetes that is more than one
version ahead of the version currently running on the master nodes, you must upgrade
to each intermediate version in sequence without skipping versions (as described in the
Kubernetes documentation).
l To successfully upgrade master nodes in a cluster, the Kubernetes Dashboard service
must be of type ClusterIP. If the Kubernetes Dashboard service is not of type ClusterIP
(for example, if the service is of type NodePort), the upgrade will fail. In this case,
change the type of the Kubernetes Dashboard service back to ClusterIP (for example,
by entering kubectl -n kube-system edit service kubernetes-dashboard and
changing the type).
l Prior to Kubernetes version 1.14, Container Engine for Kubernetes created clusters with
kube-dns as the DNS server. However, from Kubernetes version 1.14 onwards,
Container Engine for Kubernetes creates clusters with CoreDNS as the DNS server.
When you upgrade a cluster created by Container Engine for Kubernetes from an earlier
version to Kubernetes 1.14 or later, the cluster's kube-dns server is automatically
replaced with the CoreDNS server. Note that if you customized kube-dns behavior using
the original kube-dns ConfigMap, those customizations are not carried forward to the
CoreDNS ConfigMap. You will have to create and apply a new ConfigMap containing the
customizations to override settings in the CoreDNS Corefile. For more information
about upgrading to CoreDNS, see Configuring DNS Servers for Kubernetes Clusters.
Important: After you’ve upgraded master nodes to a newer Kubernetes version, you can’t
downgrade the master nodes to an earlier Kubernetes version. It’s therefore important that
before you upgrade the Kubernetes version running on the master nodes, you test that
applications deployed on the cluster are compatible with the new Kubernetes version.
1. In the Console, open the navigation menu. Under Solutions and Platform, go to
Developer Services and click Container Clusters.
2. Choose a Compartment you have permission to work in.
3. On the Cluster List page, click the name of the cluster where you want to upgrade the
Kubernetes version running on the master nodes.
If a newer Kubernetes version is available than the one running on the master nodes in
the cluster, the Upgrade button is enabled at the top of the Cluster page.
4. Click Upgrade to upgrade the master nodes to a newer version.
5. In the Upgrade Cluster Master dialog box, select the Kubernetes version to which to
upgrade the master nodes, and click Upgrade.
The Kubernetes version running on the master nodes is upgraded. From now on, the new
Kubernetes version will appear as an option when you’re defining new node pools for the
cluster.
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.
Use the UpdateCluster operation to upgrade the version of Kubernetes running on the master
nodes.
l Perform an 'in-place' upgrade of a node pool in the cluster, by specifying a more recent
Kubernetes version for new worker nodes starting in the existing node pool. First, you
modify the existing node pool's properties to specify the more recent Kubernetes
version. Then, you 'drain' existing worker nodes in the node pool to prevent new pods
starting, and to delete existing pods. Finally, you terminate each of the worker nodes in
turn. When new worker nodes are started in the existing node pool, they run the more
recent Kubernetes version you specified. See Performing an In-Place Worker Node
Upgrade by Updating an Existing Node Pool.
l Perform an 'out-of-place' upgrade of a node pool in the cluster, by replacing the original
node pool with a new node pool. First, you create a new node pool with a more recent
Kubernetes version. Then, you 'drain' existing worker nodes in the original node pool to
prevent new pods starting, and to delete existing pods. Finally, you delete the original
node pool. When new worker nodes are started in the new node pool, they run the more
recent Kubernetes version you specified. See Performing an Out-of-Place Worker Node
Upgrade by Replacing an Existing Node Pool with a New Node Pool.
l The more recent Kubernetes version you specify for the worker nodes in the node pool
must be compatible with the Kubernetes version running on the master nodes in the
cluster. See Upgrading Clusters to Newer Kubernetes Versions).
l You must drain existing worker nodes in the original node pool. If you don't drain the
worker nodes, workloads running on the cluster are subject to disruption.
You can upgrade the version of Kubernetes running on worker nodes in a node pool by
specifying a more recent Kubernetes version for the existing node pool. For each worker
node, you first drain it to prevent new pods starting and to delete existing pods. You then
terminate the worker node so that a new worker node is started, running the more recent
Kubernetes version you specified. When new worker nodes are started in the existing node
pool, they run the more recent Kubernetes version you specified.
1. In the Console, open the navigation menu. Under Solutions and Platform, go to
Developer Services and click Container Clusters.
2. Choose a Compartment you have permission to work in.
3. On the Cluster List page, click the name of the cluster where you want to change the
Kubernetes version running on worker nodes.
4. On the Cluster page, display the Node Pools tab, and click the name of the node pool
where you want to upgrade the Kubernetes version running on the worker nodes.
5. On the Node Pool page, click Edit and in the Version field, specify the required
Kubernetes version for worker nodes.
The Kubernetes version you specify must be compatible with the version that is running
on the master nodes.
You can 'upgrade' the version of Kubernetes running on worker nodes in a node pool by
replacing the original node pool with a new node pool that has new worker nodes running the
appropriate Kubernetes version. Having drained existing worker nodes in the original node
pool to prevent new pods starting and to delete existing pods, you can then delete the original
node pool. When new worker nodes are started in the new node pool, they run the more
recent Kubernetes version you specified.
To perform an 'out-of-place' upgrade of a node pool in a cluster, by creating a new node pool
to 'upgrade' the Kubernetes version on worker nodes:
1. In the Console, open the navigation menu. Under Solutions and Platform, go to
Developer Services and click Container Clusters.
2. Choose a Compartment you have permission to work in.
3. On the Cluster List page, click the name of the cluster where you want to change the
Kubernetes version running on worker nodes.
4. On the Cluster page, display the Node Pools tab, and then click Add Node Pool to
create a new node pool and specify the required Kubernetes version for its worker
nodes.
The Kubernetes version you specify must be compatible with the version that is running
on the master nodes.
5. If there are labels attached to worker nodes in the original node pool and those labels
are used by selectors (for example, to determine the nodes on which to run pods), then
use the kubectl label nodes command to attach the same labels to the new worker
nodes in the new node pool. See Assigning Pods to Nodes in the Kubernetes
documentation.
6. For the first worker node in the original node pool, prevent new pods from starting and
delete existing pods by entering kubectl drain <node_name>
For more information:
l about using kubectl, see Accessing a Cluster Using Kubectl
l about the drain command, see drain in the Kubernetes documentation
Recommended: Leverage pod disruption budgets as appropriate for your application to
ensure that there's a sufficient number of replica pods running throughout the drain
operation.
7. Repeat the previous step for each remaining worker node in the node pool, until all the
worker nodes have been drained from the original node pool.
When you have drained all the worker nodes from the original node pool and pods are
running on worker nodes in the new node pool, you can delete the original node pool.
8. On the Cluster page, display the Node Pools tab, and then select Delete Node Pool
from the Actions menu beside the original node pool.
The original node pool and all its worker nodes are deleted.
To 'upgrade' the image running on worker nodes in a node pool (for example, to upgrade to a
new version of Oracle Linux), you replace the original node pool with a new node pool that has
new worker nodes running the appropriate image. Having 'drained' existing worker nodes in
the original node pool to prevent new pods starting and to delete existing pods, you can then
delete the original node pool.
1. In the Console, open the navigation menu. Under Solutions and Platform, go to
Developer Services and click Container Clusters.
2. Choose a Compartment you have permission to work in.
3. On the Cluster List page, click the name of the cluster where you want to change the
image running on worker nodes.
4. On the Cluster page, display the Node Pools tab, and then click Add Node Pool to
create a new node pool and specify the required image for its worker nodes.
5. If there are labels attached to worker nodes in the original node pool and those labels
are used by selectors (for example, to determine the nodes on which to run pods), then
use the kubectl label nodes command to attach the same labels to the new worker
nodes in the new node pool. See Assigning Pods to Nodes in the Kubernetes
documentation.
6. For each worker node in the original node pool, prevent new pods from starting and
delete existing pods by entering kubectl drain <node_name> for each worker node.
For more information:
l about using kubectl, see Accessing a Cluster Using Kubectl
l about the drain command, see drain in the Kubernetes documentation
Prior to Kubernetes version 1.14, Container Engine for Kubernetes created clusters with kube-
dns as the DNS server. However, from Kubernetes version 1.14 onwards, Container Engine
for Kubernetes creates clusters with CoreDNS as the DNS server. CoreDNS is a general-
purpose authoritative DNS server that is modular and pluggable.
When you upgrade a cluster created by Container Engine for Kubernetes from an earlier
version to Kubernetes 1.14 or later, the cluster's kube-dns server is automatically replaced
with the CoreDNS server. Note that if you customized kube-dns behavior using the original
kube-dns ConfigMap, those customizations are not carried forward to the CoreDNS ConfigMap.
You will have to create and apply a new ConfigMap containing the customizations to override
settings in the CoreDNS Corefile.
For more information about CoreDNS customization and Kubernetes, see the Kubernetes
documentation and the CoreDNS documentation.
For example:
apiVersion: v1
kind: ConfigMap
metadata:
name: coredns-custom
namespace: kube-system
data:
example.server: | # All custom server files must have a “.server” file extension.
# Change example.com to the domain you wish to forward.
example.com {
# Change 1.1.1.1 to your customer DNS resolver.
forward . 1.1.1.1
}
For more information about the ConfigMap options to use to customize CoreDNS
behavior, see the Kubernetes documentation and the CoreDNS documentation.
2. Create the ConfigMap by running kubectl apply -f <filename>.yaml
3. Verify the customizations have been applied by running kubectl get configmaps --
namespace=kube-system coredns-custom -o yaml
4. Force CoreDNS to reload the ConfigMap by running kubectl delete pod --namespace
kube-system -l k8s-app=kube-dns
Note
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx:1.7.9
ports:
- containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
name: my-nginx-svc
labels:
app: nginx
spec:
type: LoadBalancer
ports:
- port: 80
selector:
app: nginx
The first part of the configuration file defines an Nginx deployment, requesting that it be
hosted on 3 pods running the nginx:1.7.9 image, and accept traffic to the containers on port
80.
The second part of the configuration file defines the Nginx service, which uses type
LoadBalancer to balance Nginx traffic on port 80 amongst the available pods.
To create the deployment and service defined in nginx_lb.yaml while connected to your
Kubernetes cluster, enter the command:
$ kubectl apply -f nginx_lb.yaml
This command outputs the following upon successful creation of the deployment and the load
balancer:
deployment "my-nginx" created
service "my-nginx-svc" created
The load balancer may take a few minutes to go from a pending state to being fully
operational. You can view the current state of your cluster by entering kubectl get all,
where your output looks similar to the following:
$ kubectl get all
The output shows that the my-nginx deployment is running on 3 pods (the po/my-nginx
entries), that the load balancer is running (svc/my-nginx-svc) and has an external IP
(192.0.2.22) that clients can use to connect to the app that's deployed on the pods.
spec:
replicas: 2
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx
ports:
- containerPort: 80
---
kind: Service
apiVersion: v1
metadata:
name: nginx-service
annotations:
service.beta.kubernetes.io/oci-load-balancer-ssl-ports: "443"
service.beta.kubernetes.io/oci-load-balancer-tls-secret: ssl-certificate-secret
spec:
selector:
app: nginx
type: LoadBalancer
ports:
- name: http
port: 80
targetPort: 80
- name: https
port: 443
targetPort: 80
The Load Balancer's annotations are of particular importance. The ports on which to support
https traffic are defined by the value of service.beta.kubernetes.io/oci-load-balancer-
ssl-ports. You can declare multiple SSL ports by using a comma-separated list for the
annotation's value. For example, you could set the annotation's value to "443, 3000" to
support SSL on ports 443 and 3000.
The following command creates a self-signed certificate, tls.crt, with its corresponding key,
tls.key:
$ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout tls.key -out tls.crt -subj
"/CN=nginxsvc/O=nginxsvc"
Now that you created the certificate, you need to store both it and its key as a secret in
Kubernetes. The name of the secret must match the name from the
service.beta.kubernetes.io/oci-load-balancer-tls-secret annotation of the load
balancer's definition. Use the following command to create a TLS secret in Kubernetes, whose
key and certificate values are set by --key and --cert, respectively.
$ kubectl create secret tls ssl-certificate-secret --key tls.key --cert tls.crt
You must create the Kubernetes secret before you can create the service, since the service
references the secret in its definition. Create the service using the following command:
$ kubectl create -f manifests/demo/nginx-demo-svc-ssl.yaml
Watch the service and wait for a public IP address (EXTERNAL-IP) to be assigned to the Nginx
service (nginx-service). This is the load balancer IP to use to connect to the service.
$ kubectl get svc --watch
The load balancer is now running, which means the service can now be accessed using either
http or https, as demonstrated by the following commands:
$ curl http://198.51.100.1
The "--insecure" flag is used to access the service using https due to the use of self-signed
certificates in this example. Do not use this flag in a production environment where the public
certificate was signed by a certificate authority.
Note: When a cluster is deleted, a load balancer that's dynamically created when a service is
created will not be removed. Before deleting a cluster, delete the service, which in turn will
result in the cloud provider removing the load balancer. The syntax for this command is:
$ kubectl delete svc SERVICE_NAME
For example, to delete the service from the previous example, enter:
$ kubectl delete svc nginx-service
l When you create a 'custom' cluster, you select an existing VCN that contains the
network resources to be used by the new cluster. If you want to use load balancers to
control traffic into the VCN, you select existing public or private subnets in that VCN to
host the load balancers.
l When you create a 'quick cluster', the VCN that's automatically created contains a public
regional subnet to host a load balancer. If you want to host load balancers in private
subnets, you can add private subnets to the VCN later.
Alternatively, you can create an internal load balancer service in a cluster to enable other
programs running in the same VCN as the cluster to access services in the cluster. You can
host internal load balancers in public subnets and private subnets.
To create an internal load balancer hosted on a public subnet, add the following annotation in
the metadata section of the manifest file:
service.beta.kubernetes.io/oci-load-balancer-internal: "true"
To create an internal load balancer hosted on a private subnet, add both following annotations
in the metadata section of the manifest file:
service.beta.kubernetes.io/oci-load-balancer-internal: "true"
service.beta.kubernetes.io/oci-load-balancer-subnet1: "ocid1.subnet.oc1..aaaaaa....vdfw"
For example:
apiVersion: v1
kind: Service
metadata:
name: my-nginx-svc
labels:
app: nginx
annotations:
service.beta.kubernetes.io/oci-load-balancer-internal: "true"
service.beta.kubernetes.io/oci-load-balancer-subnet1: "ocid1.subnet.oc1..aaaaaa....vdfw"
spec:
type: LoadBalancer
ports:
- port: 8100
selector:
app: nginx
To specify an alternative shape for a load balancer, add the following annotation in the
metadata section of the manifest file:
service.beta.kubernetes.io/oci-load-balancer-shape: <value>
where value is the bandwidth of the shape (for example, 100Mbps, 400Mbps, 8000Mbps).
For example:
apiVersion: v1
kind: Service
metadata:
name: my-nginx-svc
labels:
app: nginx
annotations:
service.beta.kubernetes.io/oci-load-balancer-shape: 400Mbps
spec:
type: LoadBalancer
ports:
- port: 80
selector:
app: nginx
Note: Sufficient load balancer quota must be available in the region for the shape you specify.
Enter the following kubectl command to confirm that load balancer creation did not fail due to
lack of quota:
$ kubectl describe service <service-name>
To explicitly specify a maximum idle time, add the following annotation in the metadata
section of the manifest file:
service.beta.kubernetes.io/oci-load-balancer-connection-idle-timeout: <value>
For example:
apiVersion: v1
kind: Service
metadata:
name: my-nginx-svc
labels:
app: nginx
annotations:
service.beta.kubernetes.io/oci-load-balancer-connection-idle-timeout: 100
spec:
type: LoadBalancer
ports:
- port: 80
selector:
app: nginx
Note that if you don't explicitly specify a maximum idle time, a default value is used. The
default value depends on the type of listener:
To explicitly specify a security list management mode, add the following annotation in the
metadata section of the manifest file:
service.beta.kubernetes.io/oci-load-balancer-security-list-management-mode: <value>
l "All": All required security list rules for load balancer services are managed.
l "Frontend": Only security list rules for ingress to load balancer services are managed.
You have to set up a rule that allows inbound traffic to the appropriate ports for node
port ranges, the kube-proxy health port, and the health check port ranges.
l "None": No security list management is enabled. You have to set up a rule that allows
inbound traffic to the appropriate ports for node port ranges, the kube-proxy health
port, and the health check port ranges. Additionally, you have to set up rules to allow
inbound traffic to load balancers.
For example:
apiVersion: v1
kind: Service
metadata:
name: my-nginx-svc
labels:
app: nginx
annotations:
service.beta.kubernetes.io/oci-load-balancer-security-list-management-mode: "Frontend"
spec:
type: LoadBalancer
ports:
- port: 80
selector:
app: nginx
To explicitly specify the load balancer listener protocol, add the following annotation in the
metadata section of the manifest file:
service.beta.kubernetes.io/oci-load-balancer-backend-protocol: <value>
where <value> is the protocol that defines the type of traffic accepted by the listener. For
example, "HTTP". To get a list of valid protocols, use the ListProtocols operation.
For example:
apiVersion: v1
kind: Service
metadata:
name: my-nginx-svc
labels:
app: nginx
annotations:
service.beta.kubernetes.io/oci-load-balancer-backend-protocol: "HTTP"
spec:
type: LoadBalancer
ports:
- port: 80
selector:
app: nginx
Note that if you don't explicitly specify a protocol, "TCP" is used as the default value.
A persistent volume offers persistent storage that enables your data to remain intact,
regardless of whether the containers to which the storage is connected are terminated.
A persistent volume claim (PVC) is a request for storage, which is met by binding the PVC to a
persistent volume (PV). A PVC provides an abstraction layer to the underlying storage. For
example, an administrator could create a number of static persistent volumes that can later
be bound to one or more persistent volume claims. If none of the static persistent volumes
match the user's PVC request, the cluster may attempt to dynamically create a new PV that
matches the PVC request.
With Oracle Cloud Infrastructure as the underlying IaaS provider, you can provision persistent
volume claims by attaching volumes from the Block Storage service.
Note
You use the Oracle Cloud Infrastructure Block Volume service to provision persistent volume
claims by specifying storageClassName: "oci" in the yaml file that defines the PVC.
The minimum amount of persistent storage that a PVC can request is 50 gigabytes. If the
request is for less than 50 gigabytes, the request is rounded up to 50 gigabytes.
In this example, the cluster administrator has not created any suitable PVs that match the PVC
request. As a result, the PVC will dynamically create the PV.
- ReadWriteOnce
resources:
requests:
storage: 50Gi
Enter the following command to create the PVC from the bvs-pvc.yaml file:
$ kubectl create -f bvs-pvc.yaml
Verify that the PVC has been created and bound to a new persistent volume by calling kubectl
get pvc:
$ kubectl get pvc
You can use this persistent volume when creating other objects, such as pods. For example,
the following pod definition instructs the system to use the mynginxclaim PVC as the nginx
volume, which is mounted by the pod as /data.
#nginx Pod
apiVersion: v1
kind: Pod
metadata:
name: nginx
spec:
containers:
- name: nginx
image: nginx:latest
ports:
- name: http
containerPort: 80
volumeMounts:
- name: data
mountPath: /data
volumes:
- name: nginx
persistentVolumeClaim:
claimName: mynginxclaim
In this example, the cluster administrator has created a volume backup for you to use when
provisioning a new persistent volume claim. The volume backup comes with data ready for
use by other objects such as pods.
You define a PVC in a file called pvcfrombackup.yaml file. The annotation element
volume.beta.kubernetes.io/oci-volume-source refers to the volume backup by its OCID.
For example:
kind: PersistentVolumeClaim
apiVersion: v1
metadata:
name: myvolume
annotations:
volume.beta.kubernetes.io/oci-volume-source: ocid1.volumebackup.oc1.iad.abuw...
spec:
selector:
matchLabels:
failure-domain.beta.kubernetes.io/zone: US-ASHBURN-AD-1
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 50Gi
Enter the following command to create the PVC from the pvcfrombackup.yaml file:
$ kubectl create -f pvcfrombackup.yaml
Verify that the PVC has been created and bound to a new persistent volume created from the
volume backup by calling kubectl get pvc:
$ kubectl get pvc
You can use the new persistent volume created from the volume backup when defining other
objects, such as pods. For example, the following pod definition instructs the system to use
the myvolume PVC as the nginx volume, which is mounted by the pod as /data.
#nginx Pod
apiVersion: v1
kind: Pod
metadata:
name: nginx
spec:
containers:
- name: nginx
image: nginx:latest
ports:
- name: http
containerPort: 80
volumeMounts:
- name: data
mountPath: /data
volumes:
- name: nginx
persistentVolumeClaim:
claimName: myvolume
OCI Service Broker for Kubernetes is an implementation of the Open Service Broker API. OCI
Service Broker for Kubernetes is specifically for interacting with Oracle Cloud Infrastructure
services from Kubernetes clusters. It includes three service broker adapters to bind to the
following Oracle Cloud Infrastructure services:
l Object Storage
l Autonomous Transaction Processing
l Autonomous Data Warehouse
You can add OCI Service Broker for Kubernetes to clusters you've created with Oracle Cloud
Infrastructure Container Engine for Kubernetes to interact with the Oracle Cloud
Infrastructure services listed above. Having added OCI Service Broker for Kubernetes to a
cluster, you don't have to manually provision and de-provision the Oracle Cloud Infrastructure
services each time you deploy or un-deploy an application on the cluster. Instead, you
interact with the Oracle Cloud Infrastructure services by using kubectl to call the Open Service
Broker APIs implemented by OCI Service Broker for Kubernetes .
OCI Service Broker for Kubernetes is available as a Helm chart, a Docker container, and as
source code from Github.
For more information about OCI Service Broker for Kubernetes, see the OCI Service Broker
for Kubernetes documentation in the Github repository.
1. Install OCI Service Broker for Kubernetes. During this step, you will typically:
l Install the Service Catalog.
l Install the svcat tool.
l Deploy OCI Service Broker for Kubernetes.
l Grant RBAC permissions and roles.
l Register OCI Service Broker for Kubernetes.
For more information about installation, see the OCI Service Broker for Kubernetes
documentation in the Github repository.
2. Secure OCI Service Broker for Kubernetes. During this step, you will typically:
l Restrict access to Service Catalog resources using RBAC permissions and roles.
l Configure TLS for OCI Service Broker for Kubernetes.
l Set up an Oracle Cloud Infrastructure user for use by OCI Service Broker for
Kubernetes.
l Set up appropriate policies to control access to resources (according to the Oracle
Cloud Infrastructure services to be used).
l Limit access to the OCI Service Broker for Kubernetes endpoint using
NetworkPolicy.
l Stand up an etcd cluster for Service Catalog and OCI Service Broker for
Kubernetes.
l Protect sensitive values by creating secrets.
The security configuration to choose will depend on your particular requirements. For
more information, see the OCI Service Broker for Kubernetes documentation in the
Github repository.
3. Provision and bind to the required Oracle Cloud Infrastructure services. During this
step, you will typically:
l Provide service provision request parameters.
l Provide service binding request parameters.
l Provide service binding response credentials.
The details to provide will depend on the Oracle Cloud Infrastructure service to bind to.
For more information, see the OCI Service Broker for Kubernetes documentation in the
Github repository.
This topic explains how to set up an example ingress controller along with corresponding
access control on an existing cluster. Having set up the ingress controller, this topic describes
how to use the ingress controller with an example hello-world backend, and how to verify the
ingress controller is working as expected.
Example Components
The example includes an ingress controller and a hello-world backend.
Backend Components
1. If you haven't already done so, follow the steps to set up the cluster's kubeconfig
configuration file and (if necessary) set the KUBECONFIG environment variable to point
to the file. Note that you must set up your own kubeconfig file. You cannot access a
cluster using a kubeconfig file that a different user set up. See Setting Up Cluster
Access.
2. If your Oracle Cloud Infrastructure user is a tenancy administrator, skip the next step
and go straight to Creating the Service Account, and the Ingress Controller.
3. If your Oracle Cloud Infrastructure user is not a tenancy administrator, in a terminal
window, grant the user the Kubernetes RBAC cluster-admin clusterrole on the cluster by
entering:
$ kubectl create clusterrolebinding <my-cluster-admin-binding> --clusterrole=cluster-admin --
user=<user-OCID>
where:
l <my-cluster-admin-binding> is a string of your choice to be used as the name
for the binding between the user and the Kubernetes RBAC cluster-admin
clusterrole. For example, jdoe_clst_adm
l <user-OCID> is the user's OCID (obtained from the Console ). For example,
ocid1.user.oc1..aaaaa...zutq (abbreviated for readability).
For example:
$ kubectl create clusterrolebinding jdoe_clst_adm --clusterrole=cluster-admin --
user=ocid1.user.oc1..aaaaa...zutq
2. Create and save the file cloud-generic.yaml containing the following code to define
the ingress-nginx ingress controller service as a load balancer service:
kind: Service
apiVersion: v1
metadata:
name: ingress-nginx
namespace: ingress-nginx
labels:
app.kubernetes.io/name: ingress-nginx
app.kubernetes.io/part-of: ingress-nginx
spec:
type: LoadBalancer
selector:
app.kubernetes.io/name: ingress-nginx
app.kubernetes.io/part-of: ingress-nginx
ports:
- name: http
port: 80
targetPort: http
- name: https
port: 443
targetPort: https
3. Using the file you just saved, create the ingress-nginx ingress controller service by
running the following command:
$ kubectl apply -f cloud-generic.yaml
A TLS secret is used for SSL termination on the ingress controller. To generate the secret for
this example, a self-signed certificate is used. While this is okay for testing, for production,
use a certificate signed by a Certificate Authority.
$ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout tls.key -out tls.crt -subj
"/CN=nginxsvc/O=nginxsvc"
Note
1. Create the file hello-world-ingress.yaml containing the following code. This code
uses a publicly available hello-world image from Docker Hub. You can substitute
another image of your choice that can be run in a similar manner.
apiVersion: apps/v1
kind: Deployment
metadata:
name: docker-hello-world
labels:
app: docker-hello-world
spec:
selector:
matchLabels:
app: docker-hello-world
replicas: 3
template:
metadata:
labels:
app: docker-hello-world
spec:
containers:
- name: docker-hello-world
image: scottsbaldwin/docker-hello-world:latest
ports:
- containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
name: docker-hello-world-svc
spec:
selector:
app: docker-hello-world
ports:
- port: 8088
targetPort: 80
type: ClusterIP
name: hello-world-ing
annotations:
kubernetes.io/ingress.class: "nginx"
spec:
tls:
- secretName: tls-secret
rules:
- http:
paths:
- backend:
serviceName: docker-hello-world-svc
servicePort: 8088
The output shows a 301 redirect and a Location header that suggest that http traffic is
being redirected to https.
2. Either cURL against the https url or add the -L option to automatically follow the location
header. The -k option instructs cURL to not verify the SSL certificates.
$ curl -ikL http://129.146.214.219
HTTP/1.1 200 OK
Server: nginx/1.13.2
Date: Thu, 07 Sep 2017 15:22:30 GMT
Content-Type: text/html
Content-Length: 71
Connection: keep-alive
Last-Modified: Thu, 07 Sep 2017 15:17:24 GMT
ETag: "59b16304-47"
Accept-Ranges: bytes
Strict-Transport-Security: max-age=15724800; includeSubDomains;
The last line of the output shows the HTML that is returned from the pod whose
hostname is docker-hello-world-1732906117-0ztkm.
3. Issue the cURL request several times to see the hostname in the HTML output change,
demonstrating that load balancing is occurring:
$ curl -k https://129.146.214.219
$ curl -k https://129.146.214.219
$ curl -k https://129.146.214.219
Inspecting nginx.conf
1. Find the name of the pod running the nginx-ingress-controller ingress controller
deployment and use it with a kubectl exec command to show the contents of
nginx.conf.
$ kubectl get po -n ingress-nginx
2. Look for proxy_pass in the output. There will be one for the default backend and
another that looks similar to:
proxy_pass http://upstream_balancer;
balancer_by_lua_block {
tcp_udp_balancer.balance()
}
}
By default, pods accept traffic from any source. To enhance cluster security, pods can be
'isolated' by selecting them in a network policy (the Kubernetes NetworkPolicy resource). A
network policy is a specification of how groups of pods are allowed to communicate with each
other and other network endpoints. NetworkPolicy resources use labels to select pods and to
define rules that specify what traffic is allowed to the selected pods. If a NetworkPolicy in a
cluster namespace selects a particular pod, that pod will reject any connections that are not
allowed by any NetworkPolicy. Other pods in the namespace that are not selected by a
NetworkPolicy will continue to accept all traffic. For more information about network policies,
see the Kubernetes documentation.
Network policies are implemented by the CNI network provider. Simply creating the
NetworkPolicy resource without a CNI network provider to implement it will have no effect.
Note that not all CNI network providers implement the NetworkPolicy resource.
Clusters you create with Container Engine for Kubernetes have flannel installed as the default
CNI network provider. flannel is a simple overlay virtual network that satisfies the
requirements of the Kubernetes networking model by attaching IP addresses to containers.
For more information about flannel, see the flannel documentation.
Although flannel satisfies the requirements of the Kubernetes networking model, it does not
support NetworkPolicy resources. If you want to enhance the security of clusters you create
with Container Engine for Kubernetes by implementing network policies, you have to install
and configure a network provider that does support NetworkPolicy resources. One such
provider is Calico (refer to the Kubernetes documentation for a list of other network
providers). Calico is an open source networking and network security solution for containers,
virtual machines, and native host-based workloads. For more information about Calico, see
the Calico documentation.
You can manually install Calico alongside flannel in clusters you have created using Container
Engine for Kubernetes.
For convenience, Calico installation instructions are included below, based on Calico version
3.10. Note that Calico installation instructions vary between Calico versions. For information
about installing different versions of Calico, always refer to the Calico documentation for
installing Calico for network policy enforcement only.
1. If you haven't already done so, follow the steps to set up the cluster's kubeconfig
configuration file and (if necessary) set the KUBECONFIG environment variable to point
to the file. Note that you must set up your own kubeconfig file. You cannot access a
cluster using a kubeconfig file that a different user set up. See Setting Up Cluster
Access.
2. In a terminal window, download the Calico policy-only manifest for the Kubernetes
API datastore by entering:
$ curl https://docs.projectcalico.org/v3.10/manifests/calico-policy-only.yaml -o calico.yaml
Note that the url differs, according to the version of Calico that you want to install. Refer
to the Calico documentation for instructions to install a particular version of Calico.
3. The calico.yaml file includes multiple references to the pod CIDR block value. In the
downloaded calico.yaml file, the pod CIDR block value is initially set to 192.168.0.0/16.
If the pod CIDR block value of the cluster created by Container Engine for Kubernetes is
192.168.0.0/16, skip this step. However, if the pod CIDR block value of the cluster
created by Container Engine for Kubernetes is a different value (such as the default
value of 10.244.0.0/16), you have to change the initial value in the calico.yaml file. The
steps below show one way to do that:
a. Set the value of an environment variable to the pod CIDR block value. For
example, by entering a command like:
$ export POD_CIDR="10.244.0.0/16"
b. Replace the default value 192.168.0.0/16 in the calico.yaml file with the actual
pod CIDR block value of the cluster created by Container Engine for Kubernetes.
For example, by entering a command like:
$ sed -i -e "s?192.168.0.0/16?$POD_CIDR?g" calico.yaml
4. The calico.yaml file defines a deployment named calico-typha, which has a replica count
of 1 by default. You might want to consider changing this default replica count for large
clusters or production environments. Calico recommends:
Note that the way to set the replica count differs, according to the Calico version you've
installed. Refer to the Calico documentation to find out how to set the replica count for
the version you've installed.
5. Install and configure Calico by entering the following command:
$ kubectl apply -f calico.yaml
For NetworkPolicy examples and how to use them, see the Calico documentation and
specifically:
Note that the examples vary, according to the Calico version you've installed.
This topic describes the metrics emitted by Container Engine for Kubernetes in the oci_oke
metric namespace.
To view a default set of metrics charts in the Console, navigate to the cluster you're interested
in, and then click Metrics. You also can use the Monitoring service to create custom queries.
Prerequisites
IAM policies: To monitor resources, 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. The policy must give you access to the monitoring services as well as the
resources being monitored. 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 more information on
user authorizations for monitoring, see the Authentication and Authorization section for the
related service: Monitoring or Notifications.
RESOURCEID
RESOURCEDISPLAYNAME
RESPONSEC ODE
RESPONSEGROUP
The response code group, based on the response code's first digit (for example, 2xx, 3xx,
4xx, 5xx).
CLUSTERID
NODEPOOLID
NODESTATE
The state of the compute instance hosting the worker node, as indicated by the Compute
service. For example, ACTIVE, CREATING, DELETING, DELETED, FAILED, UPDATING,
INACTIVE.
NODEC ONDITION
The condition of the worker node, as indicated by the Kubernetes API server. For
example, Ready, MemoryPressure, PIDPressure, DiskPressure, NetworkUnavailable.
For more information about monitoring metrics and using alarms, see Monitoring
Overview. For information about notifications for alarms, see Notifications Overview.
I know the Kubernetes API server returned The responses Confirm Adjust the
some error responses but the API Server might have the Start Start Time
Response Count chart doesn't show been returned Time and and End
them. outside the End Time as
time period Time necessary.
covered by cover the
the API period
Server when the
Response responses
Count chart. were
returned.
I know the Kubernetes API server returned Although the Confirm Adjust the
some error responses but the API Server responses the x- x-axis
Response Count chart doesn't show were returned axis (window
them, even though the responses were between the (window of data
returned between the Start Time and End Start Time of data display)
Time. and End display) as
Time, the x- covers necessary.
axis the period
(window of when the
data responses
display) were
might be returned.
excluding the
responses.
Note
Data transfer and export are supported in US East (Ashburn), US West (Phoenix), Germany
Central (Frankfurt), and UK South (London).
Note
You send your data as files on encrypted commodity disk to an Oracle transfer site.
Operators at the Oracle transfer site upload the files into your designated Object Storage
bucket in your tenancy.
This transfer solution requires you to source and purchase the disk used to transfer data
to Oracle Cloud Infrastructure. The disk is shipped back to you after the data is
successfully uploaded.
You send your data as files on secure, high-capacity, Oracle-supplied storage appliances
to an Oracle transfer site. Operators at the Oracle transfer site upload the data into your
designated Object Storage bucket in your tenancy.
This solution supports data transfer when you are migrating a large volume of data and
when using a transfer disk is not a practical alternative. You do not need to write any code
or purchase any hardware. Oracle supplies the transfer appliance and software required
to manage the transfer.
You export your data from your Oracle Cloud Infrastructure Object Storage bucket to your
data center using an Oracle-provided appliance.
This solution is useful if you have media content or processed datasets you need to share
with a customer or business partner.
See Service Limits for a list of applicable limits and instructions for requesting a limit
increase. To set compartment-specific limits on a resource or resource family, administrators
can use compartment quotas.
Tagging Resources
Apply tags to your resources to help organize them according to your business needs. You can
apply tags at the time you create a resource, or you can update the resource later with the
wanted tags. For general information about applying tags, see Resource Tags.
Events for objects are handled differently than other resources. Objects do not emit events by
default. Use the Console, CLI, or API to enable a bucket to emit events for object state
changes. You can enable events for object state changes during or after bucket creation.
Notifications
You can set up different types of notifications to alert you when any change happens to during
your data transfer. See Notifications Overview.
Note
You can also set up notifications for appliance-based import and export jobs using a CLI
command. The notifications run from the CLI provides a more convenient process than using
the Notifications and Events services. Instructions for setting these CLI-based notifications
are in the Preparation topics for appliance-based import and export.
What's Next
Now you are ready to prepare for your data transfer or export. See the following pages for
more information on each of the data transfer or export methods:
An import disk is a user-supplied storage device that is specially prepared to copy and
upload data to Oracle Cloud Infrastructure. You copy your data to the import disk and ship
it in a parcel to Oracle to upload your data.
Disk-Based Data Import supports external USB 2.0/3.0 hard disk drives.
Note
TRANSFER DISK
A transfer disk is the logical representation of an import disk that has been prepared to
copy and upload data to Oracle Cloud Infrastructure.
Note
TRANSFER JOB
The Data Transfer Utility is the command line software that Oracle provides for you to
prepare the transfer disk for your data and for shipment to Oracle. In addition, you can
use this software to manage transfer jobs and packages.
Note
DATA HOST
The host computer on your site that stores the data you intend to copy to the disk for
migration to Oracle Cloud Infrastructure.
Note
TRANSFER PACKAGE
A transfer package is the logical representation of the parcel containing the transfer disk
that you ship to Oracle to upload to Oracle Cloud Infrastructure.
BUCKET
The logical container in Oracle Cloud Infrastructure Object Storage where Oracle
operators upload your data. A bucket is associated with a single compartment in your
tenancy whose policies that determine what actions a user can perform.
A new or existing IAM user that has the authorization and permissions to create and
manage transfer jobs.
A temporary IAM user that grants Oracle personnel the authorization and permissions to
upload the data from your transfer disk to your designated Oracle Cloud Infrastructure
Object Storage bucket. Delete this temporary user after your data is uploaded to Oracle
Cloud Infrastructure.
l Project Sponsor: Responsible for the overall success of the data transfer. Project
Sponsors usually have complete access to their organization's Oracle Cloud
Infrastructure tenancy. They coordinate with the other roles in the organization to
complete the implementation of data transfer project. The Project Sponsor is also
responsible for signing legal documentation and setting up notifications for the data
import.
l Infrastructure Engineer: Responsible for integrating the transfer appliance into the
organization's IT infrastructure from where the data is being transferred. Tasks
associated with this role include connecting the transfer appliance to power, placing it
within the network, and setting the IP address through a serial console menu using the
provided USB-to-Serial adapter.
l Data Administrator: Responsible for identifying and preparing the data to be
transferred to Oracle Cloud Infrastructure. This person usually has access to, and
expertise with, the data being migrated.
These roles correspond to the various phases of the data transfer described in the following
section. A specific role can be responsible for one or more phases.
l The Data Transfer Utility uses the standard Linux dm-crypt and LUKS utilities to encrypt
block devices.
l The dm-crypt software generates a master AES-256 bit encryption key that is used for
all data written to or read from the disk. That key is protected by an encryption
passphrase that the user must know to access the encrypted data.
l When the data transfer administrator uses the Data Transfer Utility to create a disk,
Oracle Cloud Infrastructure creates a strong encryption passphrase that is displayed to
the user and passed to dm-crypt. The passphrase is displayed to standard output only
once and cannot be retrieved again. Copy this passphrase to a durable, secure location
for future reference.
l For extra security, you can also encrypt your own data with your own encryption keys.
Before copying your data to the transfer disk, you can encrypt your data with a tool and
encryption key of your choosing. After the data has been uploaded, you would need to
use the same tool and encryption key to access the data.
l All network communication between the Data Transfer Utility and Oracle Cloud
Infrastructure is encrypted in-transit using Transport Layer Security (TLS).
l After copying your data to a transfer disk, generate a manifest file using the Data
Transfer Utility. The manifest contains an index of all of the copied files and generated
data integrity hashes. The Data Transfer Utility copies the config_upload_user
configuration file and referenced IAM credentials to the encrypted transfer disk. This
configuration file describes the temporary IAM data transfer upload user. Oracle uses
the credentials and entries defined in the config_upload_user file when processing the
transfer disk and uploading files to Oracle Cloud Infrastructure Object Storage.
Note
Oracle cannot upload data from a transfer disk without the correct credentials defined in
this configuration file. See Data Transfer Utility for more information about the required
configuration files.
l When you disconnect or lock a transfer disk using the Data Transfer Utility, the original
encryption passphrase is required to once again access the disk. If the encryption
passphrase is not known or lost, you cannot access the data on the transfer disk. To
reuse a transfer disk, you must reformat the disk. Reformatting a disk removes all the
data.
l Oracle retrieves the encryption passphrase for a transfer disk from Oracle Cloud
Infrastructure. Oracle uses the passphrase to decrypt, mount the transfer disk, and
upload the data to the designated bucket in the tenancy.
l After processing a transfer package, Oracle returns the transfer disk attached to the
transfer package using the return shipping label you provide.
l To protect your data, we make the data on the disk unrecoverable before shipping the
transfer disk back to you. To comply with customs regulations, we wipe the disk
completely before shipping it back to international shipping addresses.
l The Data Transfer Utility is a full-featured command line tool for disk-based data
transfers only (appliance-based data transfers use a different command line tool). For
more information and installation instructions, see Data Transfer Utility.
l The Console is an easy-to-use, partial-featured browser-based interface. For more
information, see Signing In to the Console.
Note
What's Next
You are now ready to begin preparation for the Disk-Based Data Import. See Preparing for
Disk Data Transfers for more information.
This topic describes the tasks associated with preparing for the Disk-Based Data Import. The
Project Sponsor role typically performs these tasks. See Roles and Responsibilities.
Each service in Oracle Cloud Infrastructure integrates with IAM for authentication and
authorization.
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.
Access to resources is provided to groups using policies and then inherited by the users that
are assigned to those groups. Data transfer requires the creation of two distinct groups:
l Data transfer administrators who can create and manage transfer jobs.
l Data transfer upload users who can upload data to Object Storage. For your data
security, the permissions for upload users allow Oracle personnel to upload standard
and multi-part objects on your behalf and inspect bucket and object metadata. The
permissions do not allow Oracle personnel to inspect the actual data.
The Data Administrator is responsible for generating the required RSA keys needed for the
temporary upload users. These keys should never be shared between users.
l The data transfer administrator group requires an authorization policy that includes the
following:
Allow group <group_name> to manage data-transfer-jobs in compartment <compartment_name>
Alternatively, you can consolidate the manage buckets and manage objects policies
into the following:
Allow group <group_name> to manage object-family in compartment <compartment_name>
l The data transfer upload user group requires an authorization policy that includes the
following:
Allow group <group_name> to manage buckets in compartment <compartment_name> where all {
request.permission='BUCKET_READ', target.bucket.name='<bucket_name>' }
The Oracle Cloud Infrastructure administrator then adds a user to each of the data transfer
groups created. For details on creating users, see Managing Users.
Important
The Object Storage service is used to upload your data to Oracle Cloud Infrastructure. Object
Storage stores objects in a container called a bucket within a compartment in your tenancy.
For details on creating the bucket to store uploaded data, see Managing Buckets.
Ensure that your local environment's firewall can communicate with the Data Transfer Service
running on the IP address ranges: 140.91.0.0/16. You also need to open access to the Object
Storage IP address ranges: 134.70.0.0/17.
This section describes how to create a transfer job as part of the preparation for the data
transfer. See Transfer Jobs for complete details on all tasks related to transfer jobs.
Tip
A transfer job represents the collection of files that you want to transfer and signals the
intention to upload those files to Oracle Cloud Infrastructure. A transfer job combines at least
one transfer disk with a transfer package. Identify which compartment and Object Storage
bucket that Oracle is to upload your data to. Create the transfer job in the same compartment
as the upload bucket and supply a human-readable name for the transfer job. Avoid entering
confidential information when providing transfer job names.
Note
Creating a transfer job returns a job ID that you specify in other transfer tasks. For example:
ocid1.datatransferjob.region1.phx..exampleuniqueID
Optionally, you can specify one or more free-form or defined tags when you create a transfer
job. For more information about tagging, see Resource Tags.
Note
Each transfer job you create has a unique ID within Oracle Cloud Infrastructure. For example:
ocid1.datatransferjob.region1.phx..<unique_ID>
You will need to forward this transfer job ID to the Data Administrator.
Tip
The Project Sponsor is responsible for creating or obtaining configuration files that allow the
uploading of user data to the transfer appliance. Send these configuration files to the Data
Administrator where they can be placed in the Data Host. The config file is for the data
transfer administrator, the IAM user with the authorization and permissions to create and
manage transfer jobs. The config_upload_user file is for the data transfer upload user, the
temporary IAM user that Oracle uses to upload your data on your behalf.
Create a base Oracle Cloud Infrastructure directory and two configuration files with the
required credentials.
Create a Oracle Cloud Infrastructure directory (.oci) on the same Data Host where the CLI is
installed. For example:
mkdir /root/.oci/
The two configuration files (config and config_upload_user) are placed in this directory.
Create the data transfer administrator configuration file /root/.oci/config with the
following structure:
[DEFAULT]
user=<The OCID for the data transfer administrator>
fingerprint=<The fingerprint of the above user's public key>
key_file=<The _absolute_ path to the above user's private key file on the host machine>
tenancy=<The OCID for the tenancy that owns the data transfer job and bucket>
region=<The region where the transfer job and bucket should exist. Valid values are:
us-ashburn-1, us-phoenix-1, eu-frankfurt-1, and uk-london-1.>
For example:
[DEFAULT]
user=ocid1.user.oc1..exampleuniqueID
fingerprint=4c:1a:6f:a1:5b:9e:58:45:f7:53:43:1f:51:0f:d8:45
key_file=/home/user/ocid1.user.oc1..exampleuniqueID.pem
tenancy=ocid1.tenancy.oc1..exampleuniqueID
region=us-phoenix-1
For the data transfer administrator, you can create a single configuration file that contains
different profile sections with the credentials for multiple users. Then use the --profile
option to specify which profile to use in the command.
Here is an example of a data transfer administrator configuration file with different profile
sections:
[DEFAULT]
user=ocid1.user.oc1..exampleuniqueID
fingerprint=4c:1a:6f:a1:5b:9e:58:45:f7:53:43:1f:51:0f:d8:45
key_file=/home/user/ocid1.user.oc1..exampleuniqueID.pem
tenancy=ocid1.tenancy.oc1..exampleuniqueID
region=us-phoenix-1
[PROFILE1]
user=ocid1.user.oc1..exampleuniqueID
fingerprint=4c:1a:6f:a1:5b:9e:58:45:f7:53:43:1f:51:0f:d8:45
key_file=/home/user/ocid1.user.oc1..exampleuniqueID.pem
tenancy=ocid1.tenancy.oc1..exampleuniqueID
region=us-ashburn-1
By default, the DEFAULT profile is used for all CLI commands. For example:
oci dts job create --compartment-id ocid.compartment.oc1..exampleuniqueID --bucket MyBucket --display-
name MyDisplay --device-type disk
Instead, you can issue any CLI command with the --profile option to specify a different data
transfer administrator profile. For example:
oci dts job create --compartment-id ocid.compartment.oc1..exampleuniqueID --bucket MyBucket --display-
name MyDisplay --device-type disk --profile MyProfile
Using the example configuration file above, the <profile_name> would be profile1.
If you created two separate configuration files, use the following command to specify the
configuration file to use:
oci dts job create --compartment-id <compartment_id> --bucket <bucket_name> --display-name <display_
name>
The config_upload_user configuration file is for the data transfer upload user, the
temporary IAM user that Oracle uses to upload your data on your behalf. Create this
configuration file with the following structure:
[DEFAULT]
user=<The OCID for the data transfer upload user>
fingerprint=<The fingerprint of the above user's public key>
key_file=<The _absolute_ path to the above user's private key file on the host machine>
tenancy=<The OCID for the tenancy that owns the data transfer job and bucket>
region=<The region where the transfer job and bucket should exist. Valid values are:
us-ashburn-1, us-phoenix-1, eu-frankfurt-1, and uk-london-1.>
Include the line endpoint=<url> for the Object Storage API endpoint in the upload user
configuration file.
For example:
endpoint=https://objectstorage.us-phoenix-1.oraclecloud.com
A complete configuration including the Object Storage endpoint might look like this:
[DEFAULT]
user=ocid1.user.oc1..exampleuniqueID
fingerprint=4c:1a:6f:a1:5b:9e:58:45:f7:53:43:1f:51:0f:d8:45
key_file=/home/user/ocid1.user.oc1..exampleuniqueID.pem
tenancy=ocid1.tenancy.oc1..exampleuniqueID
region=us-phoenix-1
endpoint=https://objectstorage.us-phoenix-1.oraclecloud.com
Important
The following table lists the basic entries that are required for each configuration file and
where to get the information for each entry.
Note
fingerprint Fingerprint for the key pair being used. To get Yes
the value, see Required Keys and OCIDs.
You can verify the data transfer upload user credentials using the following command:
dts job verify-upload-user-credentials --bucket <bucket_name>
A transfer package is the virtual representation of the physical disk package that you are
shipping to Oracle for upload to Oracle Cloud Infrastructure. See Transfer Packages for
complete details on all tasks related to transfer packages.
Creating a transfer package requires the job ID returned from when you created the transfer
job. For example:
ocid1.datatransferjob.region1.phx..exampleuniqueID
The Data Transfer Package dialog appears displaying information such as the shipping
address, the shipping vendor, and the shipping status.
To get the transfer package label using the Data Transfer Utility
dts job show --job-id <job_id>
You can find the shipping address in the transfer package details. Use this information to
create a shipping label for the transfer package that is used to send the disk to Oracle.
To get the shipping address for a transfer package using the Console
1. Open the navigation menu. Under Core Infrastructure, go to Object Storage and
click Data Transfer - Imports.
2. Find the transfer job for which you want to see the details.
4. Find the transfer package for which you want to see the details.
To get the shipping address for a transfer package using the Data Transfer
Utility
At the command prompt on the Data Host, run dts package show to get the shipping address
for a transfer package.
dts package show --job-id <job_id> --package-label <package_label>
When you have completed all the tasks in this topic, provide the Data Administrator of the
following:
What's Next
You are now ready to configure your system for the data transfer. See Configuring Import
Disk Data Transfers.
This topic describes the tasks associated with configuring the Disk-Based Data Import. The
Infrastructure Engineer role typically performs these tasks. See Roles and Responsibilities.
Configuration for the Disk-Based Data Import consists of the following tasks:
l Attaching the import disk to the Data Host. Remove all partitions and any file systems.
To prevent the accidental deletion of data, the Data Transfer Utility does not work with
disks that already have partitions or file systems. Disks are visible to the host as block
devices and must provide a valid response to the hdparm -I <device> Linux command.
l Sending the block device path to the Data Administrator.
What's Next
You are now ready to load your data to the transfer disk. See Copying the Data to the Import
Disk.
This topic describes the tasks associated with running the data transfer from the Data Host to
the import disk. The Data Administrator role typically performs these tasks. See Roles and
Responsibilities.
Information Prerequisites
Before performing any disk copying tasks, you must obtain the following information:
l Disk block device path. The Infrastructure Engineer typically provides this information.
l IAM login information, Data Transfer Utility configuration files, transfer job ID, and
package label. The Project Sponsor typically provides this information.
The Data Transfer Utility provides a set of command line-based tools for configuring and
running disk-based data transfers. Use the Data Transfer Utility as an alternative to running
commands from the Console. Sometimes you must use the Data Transfer Utility to complete
certain tasks as there is no Console equivalent. See Data Transfer Utility for details on how to
install and configure the Data Transfer Utility for use with disk-based data transfers.
The transfer disk is the logical representation of the physical import disk that has been
configured for use for receiving data as part of the disk-based data transfer. See Transfer
Disks for complete details on all tasks related to transfer disks.
Note
When you create a transfer disk for use with the disk on which you are copying your files, the
Data Transfer Utility:
For example:
/mnt/orcdts_DJZNWK3ET
When you register a transfer disk, Oracle Cloud Infrastructure generates a strong encryption
passphrase that is used to encrypt the contents on the disk. The encryption passphrase is
displayed to standard output to the data transfer administrator user and cannot be retrieved
again. Create a local, secure copy of the encryption passphrase, so you can reference the
passphrase again.
Creating a transfer disk requires the job ID returned from when you created the transfer job
and the path to the attached disk (for example, /dev/sdb).
Copying Files
Attach the disk to the Data Host and copy files to the mount point created by the transfer disk
through the Data Transfer Utility.
Note
You can only copy regular files to disks. Special files (links, sockets, pipes, and so forth)
cannot be copied directly. To transfer special files, create a tar archive of the files and copy
the tar archive to the disk.
Note
Do not disconnect the disk until you copy all files from
the Data Host and generate the manifest file. If you
accidentally disconnect the disk before copying all files,
you must unlock the disk using the encryption
passphrase. The encryption passphrase was generated
and displayed when you created the transfer disk. If the
generated encryption passphrase is not available, you
must delete the transfer disk from the transfer job and
re-create the transfer disk. All data previously copied to
that disk is lost.
Note
After copying your data to a transfer disk, generate a manifest file using the Data Transfer
Utility. The manifest contains an index of all of the copied files and generated data integrity
hashes. The Data Transfer Utility copies the config_upload_user configuration file and
referenced IAM credentials to the encrypted transfer disk. This configuration file describes the
temporary IAM data transfer upload user. Oracle uses the credentials and entries defined in
the config_upload_user file when processing the transfer disk and uploading files to Oracle
Cloud Infrastructure Object Storage.
Note
Oracle cannot upload data from a transfer disk without the correct credentials defined in this
configuration file. See Data Transfer Utility for more information about the required
configuration files.
Note
Note
Locking a transfer disk safely unmounts the disk and removes the encryption passphrase from
the Data Host.
If you need to unlock the transfer disk, you are prompted for the encryption passphrase that
was generated when you created the transfer disk.
Attach a transfer disk to a transfer package after you have performed the following tasks:
A disk can be attached to one package, detached, and then attached to another package. In
some cases, you have attached a transfer disk to a transfer package, but have changed your
mind about shipping that disk with the transfer package. You can also detach a transfer disk
from one transfer package and attach that disk to a different transfer package.
To attach a transfer disk to a transfer package using the Data Transfer Utility
At the command prompt on the Data Host, run dts disk attach to attach a disk to a transfer
package.
dts disk attach --job-id <job_id> --package-label <package_label> --disk-label <disk_label>
To detach a transfer disk to a transfer package using the Data Transfer Utility
At the command prompt on the Data Host, run dts disk detach to detach a disk from a
transfer package.
dts disk detach --job-id <job_id> --package-label <package_label> --disk-label <disk_label>
After delivering the transfer package to the shipping vendor, update the transfer package with
the tracking information.
Important
To update the transfer package with tracking information using the Console
1. Open the navigation menu. Under Core Infrastructure, go to Object Storage and
click Data Transfer - Imports.
2. Find the transfer job for which you want to see the associated transfer packages.
6. Click Edit.
7. Enter the Tracking ID and the Return Tracking ID.
8. Click Edit Transfer Package.
To update the transfer package with tracking information using the Data
Transfer Utility
At the command prompt on the host, run dts package ship to update the transfer package
tracking information.
dts package ship --job-id <job_id> --package-label <package_label> --package-vendor <vendor_name> --
tracking-number <tracking_number> --return-tracking-number <return_tracking_number>
After completing the tasks listed in this topic, notify the Infrastructure Engineer of the
following:
What's Next
You are now ready to ship your disk with the copied data to Oracle. See Shipping Import
Disks.
This topic describes the tasks associated with shipping the import disk containing the copied
data to Oracle. The Infrastructure Engineer role typically performs these tasks. See Roles and
Responsibilities.
Do not disconnect the import disk until you copy all files from the Data Host and generate the
manifest file. See Copying the Data to the Import Disk for more information.
You should receive the shipping labels electronically from the Project Sponsor. Print them on
the appropriate labels for shipping the import disk.
GENERAL
Include the required return shipping label in the box when packaging the import disk for
shipment.
Note
Ensure that the transfer job and transfer package label are clearly readable on the outside of
the box containing the import disk.
Important
You can view the vendors available for delivery of your import disk to Oracle Cloud
Infrastructure.
Note
Note
To list the vendors available for delivering the transfer disk to Oracle Cloud
Infrastructure
At the command prompt on the Data Host, run dts package list-delivery-vendors to list
the available delivery vendors.
dts package list-delivery-vendors
Create a commercial invoice when shipping transfer disks internationally. To ensure that
packages are not held up in customs, follow these guidelines when creating the commercial
invoice:
l Show the "ship-to party" as the address provided in the transfer package details. See
Creating Shipping Labels for details.
l State that "The value shown includes the value of software and data recorded onto the
hard drive unit."
l State that the "Goods are free of charge - no payment required."
l State that the type of export is "Temporary."
l Ensure that the commodity code shows the correct HS code for a hard drive unit as
specified in the source country's HS code list.
l State the description as the manufacture's description of the hard drive unit and include
the words "Hard Disk Drive."
l Ensure that the invoice is signed and includes the printed name of the signer.
What's Next
Now you can track your transfer disk shipment and review post transfer logs and summaries.
See Monitoring the Import Disk Shipment and Data Transfer.
This topic describes the monitoring tasks to do after sending the import disk with the copied
data to Oracle for data transfer to Oracle Cloud Infrastructure. The Project Sponsor role
typically performs these tasks. See Roles and Responsibilities.
When Oracle has processed the transfer (import) disk associated with a transfer package, the
status of the transfer package changes to Processed. When Oracle has shipped the disk, the
status of the transfer package changes to Returned.
To check the status of a transfer package using the Data Transfer Utility
At the command prompt on the Data Host, run dts package show to show the status of a
transfer package.
dts package show --job-id <job_id> --package-label <package_label>
Oracle creates upload summary log files for each uploaded import disk. These logs are placed
in the bucket where the data was uploaded to Oracle Cloud Infrastructure. The upload
summary file compares the import disk's manifest file to the contents of the target Oracle
Cloud Infrastructure Object Storage bucket after file upload.
The top of the log report summarizes the overall file processing status:
P - Present: The file is present in both the disk and the target bucket
M - Missing: The file is present in the disk but not the target bucket. It was likely uploaded and then
deleted by another user before the summary was generated.
C - Name Collision: The file is present in the manifest but a file with the same name but different
contents is present in the target bucket.
U - Unreadable: The file is not readable from the disk
N - Name Too Long: The file name on disk is too long and could not be uploaded
After the import disk with your copied data is received by Oracle and the data transfer begins,
you can view the metrics associated with the transfer job in the Transfer Appliance Details
page in chart or table format.
Tip
Select the Start Time and End Time for these measures, either by manually entering the
days and times in their respective fields, or by selecting the Calendar feature and picking the
times that way. As an alternative to selecting a start and end time, you can also select from a
list of standard times (last hour, last 6 hours, and so forth) from the Quick Selects list for
the period measured. The time period you specify applies to all the measures.
Specify the Interval (for example, 5 minutes, 1 hour) that each measure is recorded from
the list.
Specify the Statistic being recorded (for example, Sum, Mean) for each measure from the
list.
Tip
Choose additional actions from the Options list, including viewing the query in the Metrics
Explorer, capturing the URL for the measure, and switching between chart and table view.
Click Reset Charts to delete any existing information in the charts and begin recording new
metrics.
See Monitoring Overview for general information on monitoring your Oracle Cloud
Infrastructure services.
Typically, you would close a transfer job when no further transfer job activity is required or
possible. Closing a transfer job requires that the status of all associated transfer packages be
returned, canceled, or deleted. In addition, the status of the associated transfer disk must be
complete, in error, missing, canceled, or deleted.
2. Find the data transfer package for which you want to display the details.
What's Next
You have completed the process of setting up, running, and monitoring the import disk-based
data transfer. After the disk contents is successfully migrated to Oracle Cloud Infrastructure,
your physical disk is erased and returned to you.
If you determine that another disk-based data transfer is required, repeat the procedure from
the beginning.
Important
The Data Transfer Utility is licensed under the Universal Permissive License 1.0 and the
Apache License 2.0. Third-party content is separately licensed as described in the code.
Note
Prerequisites
To install and use the Data Transfer Utility, obtain the following:
Note
Download and install the Data Transfer Utility installer that corresponds to your Data Host's
operating system.
X.Y.Z represents the version numbers that match the installer you downloaded.
3. Confirm that the Data Transfer Utility installed successfully.
sudo dts --version
To install the Data Transfer Utility on Oracle Linux or Red Hat Linux
1. Download the installation .rpm file.
2. Issue the yum install command as the root user that has write permissions to the
/opt directory.
X.Y.Z represents the version numbers that match the installer you downloaded.
3. Confirm that the Data Transfer Utility installed successfully.
sudo dts --version
Before using the Data Transfer Utility, you must create a base Oracle Cloud Infrastructure
directory and two configuration files with the required credentials. One configuration file is for
the data transfer administrator, the IAM user with the authorization and permissions to create
and manage transfer jobs. The other configuration file is for the data transfer upload user, the
temporary IAM user that Oracle uses to upload your data on your behalf.
Create a data transfer administrator configuration file /root/.oci/config with the following
structure:
[DEFAULT]
user=<The OCID for the data transfer administrator>
fingerprint=<The fingerprint of the above user's public key>
key_file=<The _absolute_ path to the above user's private key file on the host machine>
tenancy=<The OCID for the tenancy that owns the data transfer job and bucket>
region=<The region where the transfer job and bucket should exist. Valid values are:
us-ashburn-1, us-phoenix-1, eu-frankfurt-1, and uk-london-1.>
For example:
[DEFAULT]
user=ocid1.user.oc1..<unique_ID>
fingerprint=4c:1a:6f:a1:5b:9e:58:45:f7:53:43:1f:51:0f:d8:45
key_file=/home/user/ocid1.user.oc1..<unique_ID>.pem
tenancy=ocid1.tenancy.oc1..<unique_ID>
region=us-phoenix-1
For the data transfer administrator, you can create a single configuration file that contains
different profile sections with the credentials for multiple users. Then use the --profile
option to specify which profile to use in the command. Here is an example of a data transfer
administrator configuration file with different profile sections:
[DEFAULT]
user=ocid1.user.oc1..<unique_ID>
fingerprint=4c:1a:6f:a1:5b:9e:58:45:f7:53:43:1f:51:0f:d8:45
key_file=/home/user/ocid1.user.oc1..<unique_ID>.pem
tenancy=ocid1.tenancy.oc1..<unique_ID>
region=us-phoenix-1
[PROFILE1]
user=ocid1.user.oc1..<unique_ID>
fingerprint=4c:1a:6f:a1:5b:9e:58:45:f7:53:43:1f:51:0f:d8:45
key_file=/home/user/ocid1.user.oc1..<unique_ID>.pem
tenancy=ocid1.tenancy.oc1..<unique_ID>
region=us-ashburn-1
By default, the DEFAULT profile is used for all Data Transfer Utility commands. For example:
dts job create --compartment-id <compartment_id> --bucket <bucket_name> --display-name <display_name>
--device-type <disk>
Instead, you can issue any Data Transfer Utility command with the --profile option to
specify a different data transfer administrator profile. For example:
dts job create --compartment-id <compartment_id> --bucket <bucket_name> --display-name <display_name>
--device-type <disk> --profile <profile_name>
Using the example configuration file above, the <profile_name> would be profile1.
For example:
[DEFAULT]
user=ocid1.user.oc1..<unique_ID>
fingerprint=4c:1a:6f:a1:5b:9e:58:45:f7:53:43:1f:51:0f:d8:45
key_file=/home/user/ocid1.user.oc1..<unique_ID>.pem
tenancy=ocid1.tenancy.oc1..<unique_ID>
region=us-phoenix-1
Important
The following table lists the basic entries that are required for each configuration file and
where to get the information for each entry.
Note
fingerprint Fingerprint for the key pair being used. To get Yes
the value, see Required Keys and OCIDs.
You can verify the data transfer upload user credentials using the following command:
dts job verify-upload-user-credentials --bucket <bucket_name>
This section provides an overview of the syntax for the Data Transfer Utility.
Important
You can specify Data Transfer Utility command options using the following commands:
l --option <value> or
l --option=<value>
S YNTAX
The following examples show typical Data Transfer Utility commands to create a transfer job.
dts job create --compartment-id ocid.compartment.oc1..exampleuniqueID --display-name "mycompany
transfer1" --bucket mybucket --device-type disk
Or:
dts job create --compartment-id=compartment-id ocid.compartment.oc1..exampleuniqueID --display-
name="mycompany transfer1" --bucket=mybucket --device-type=disk
Note
You can get the installed version of the Data Transfer Utility using --version or -v. For
example:
dts --version
0.6.183
All Data Transfer Utility help commands have an associated help component you can access
from the command line. To view the help, enter any command followed by the --help or -h
option. For example:
dts job --help
Commands:
create Creates a new transfer disk or appliance job.
show Shows the transfer disk or appliance job details.
update Updates the transfer disk or appliance job details.
delete Deletes the transfer disk or appliance job.
close Closes the transfer disk or appliance job.
list Lists all transfer disk or appliance jobs.
verify-upload-user-credentials Verifies the transfer disk or appliance upload user credentials.
When you run the help option (--help or -h) for a specified command, all the subordinate
commands and options for that level of the Data Transfer Utility are displayed. If you want to
access the Data Transfer Utility help for a specific subordinate command, include it in the
Data Transfer Utility string, for example:
dts job create --help
What's Next
You are now ready to perform disk-based data transfers. See Copying the Data to the Import
Disk.
Transfer Jobs
A transfer job represents the collection of files that you want to transfer and signals the
intention to upload those files to Oracle Cloud Infrastructure. A transfer job combines at least
one transfer disk with a transfer package. Identify which compartment and Object Storage
bucket to which Oracle will upload your data.
Tip
Create the transfer job in the same compartment as the upload bucket and supply a human-
readable name for the transfer job. Avoid entering confidential information when providing
transfer job names.
Creating a transfer job returns a job ID that you specify in other transfer tasks. For example:
ocid1.datatransferjob.region1.phx..<unique_ID>
For example:
oci dts job create --bucket MyBucket1 --compartment-id ocid.compartment.oc1..exampleuniqueID --display-
name MyDiskImportJob --device-type appliance
Transfer Job :
ID : ocid1.datatransferjob.oc1..exampleuniqueID
CompartmentId : ocid.compartment.oc1..exampleuniqueID
UploadBucket : MyBucket1
Name : MyDiskImportJob
Label : JZM9PAVWH
CreationDate : 2019/06/04 17:07:05 EDT
Status : PREPARING
freeformTags : *** none ***
Optionally, you can specify one or more free-form or defined tags when you create a transfer
job. For more information about tagging, see Resource Tags.
Note
To display the list of transfer jobs using the Data Transfer Utility
dts job list --compartment-id <compartment_id>
For example:
dts job list --compartment-id ocid.compartment.oc1..exampleuniqueID
When you use the Data Transfer Utility to list jobs, tagging details are also included in the
output if you specified tags.
2. Find the transfer job for which you want to display the details.
To display the details of a transfer job using the Data Transfer Utility
dts job show --job-id <job_id>
For example:
dts job show --job-id ocid1.datatransferjob.oc1..exampleuniqueID
Transfer Job :
ID : ocid1.datatransferjob.oc1..exampleuniqueID
CompartmentId : ocid.compartment.oc1..exampleuniqueID
UploadBucket : MyBucket1
Name : MyDiskImportJob
Label : JZM9PAVWH
CreationDate : 2019/06/04 17:07:05 EDT
Status : PREPARING
freeformTags : *** none ***
definedTags : *** none ***
Packages :
[1] :
Label : PBNZOX9RU
TransferSiteShippingAddress : Oracle Data Transfer Service; Job:JZM9PAVWH Package:PBNZOX9RU ;
21111 Ridgetop Circle; Dock B; Sterling, VA 20166; USA
DeliveryVendor : FedEx
DeliveryTrackingNumber : *** none ***
ReturnDeliveryTrackingNumber : *** none ***
Status : PREPARING
Devices : [*** none ***]
UnattachedDevices : [*** none ***]
Appliances : [*** none ***]
When you use the Data Transfer Utility to display the details of a job, tagging details are also
included in the output if you specified tags.
To edit the name of a transfer job using the Data Transfer Utility
dts job update --job-id <job_id> --display-name <display_name>
<display_name> is the new name of the transfer job. Avoid entering confidential information
in the transfer job name.
For example:
dts job update --job-id
ocid1.datatransferjob.oc1.phx.aaaaaaaa4tccxsktptbexdy6ipmfqome5acvieqthlqvts6lltqv5qxo2fiq --display-
name MyRenamedJob
Transfer Job :
ID : ocid1.datatransferjob.oc1..exampleuniqueID
CompartmentId : ocid.compartment.oc1..exampleuniqueID
UploadBucket : MyBucket1
Name : MyRenamedJob
Label : JZM9PAVWH
CreationDate : 2019/06/04 17:07:05 EDT
Status : PREPARING
freeformTags : *** none ***
definedTags : *** none ***
Packages : [*** none ***]
To edit the tags associated with a transfer job using the Data Transfer Utility
The Data Transfer Utility replaces any existing tags with the new key/value pairs you
specify.
For example:
dts job update --job-id ocid1.datatransferjob.oc1..exampleuniqueID --defined-tags '{"Operations":
{"CostCenter": "42"}}'
Transfer Job :
ID : ocid1.datatransferjob.oc1..exampleuniqueID
CompartmentId : ocid.compartment.oc1..exampleuniqueID
UploadBucket : MyBucket1
Name : MyDiskImportJob
Label : JZM9PAVWH
CreationDate : 2019/06/04 17:07:05 EDT
Status : PREPARING
freeformTags : *** none ***
definedTags :
operations :
costcenter : 42
Packages : [*** none ***]
UnattachedDevices : [*** none ***]
Appliances : [*** none ***]
For example:
dts job update --job-id ocid1.datatransferjob.oc1..exampleuniqueID --freeform-tags '{"Chicago_
Team":"marketing_videos"}'
Transfer Job :
ID : ocid1.datatransferjob.oc1..exampleuniqueID
CompartmentId : ocid.compartment.oc1..exampleuniqueID
UploadBucket : MyBucket1
Name : MyDiskImportJob
Label : JZM9PAVWH
CreationDate : 2019/06/04 17:07:05 EDT
Status : PREPARING
freeform-tags :
Chicago_Team : marketing_videos
definedTags : *** none ***
Packages : [*** none ***]
UnattachedDevices : [*** none ***]
Appliances : [*** none ***]
To delete the tags associated with a transfer job using the Data Transfer Utility
The Data Transfer Utility replaces any existing tags with the new key/value pairs you
specify. If you want to delete some of the tags, you would specify new tag string that does not
contain the key/value pair you want to delete.
Partial tag deletion is handled in the same way as you edit tags:
dts job update --job-id <job_id> --defined-tags '{ "<tag_namespace>": { "<tag_key>":"<value>" }}'
Note
You are returned to the Details page for that transfer job.
<compartment_id> is the compartment to which the data transfer job is being moved.
<options> are:
l --if-match: The tag that must be matched for the task to occur for that entity. If set,
the update is only successful if the object's tag matches the tag specified in the request.
l --from-json: Provide input to this command as a JSON document from a file using the
file://path-to/file syntax. The --generate-full-command-json-input option can be
used to generate a sample JSON file to be used with this command option. The key
names are pre-populated and match the command option names (converted to
camelCase format, e.g. compartment-id --> compartmentId), while the values of the
keys need to be populated by the user before using the sample file as an input to this
command. For any command option that accepts multiple values, the value of the key
can be a JSON array. Options can still be provided on the command line. If an option
exists in both the JSON document and the command line then the command line
specified value will be used. For examples on usage of this option, please see our "using
CLI with advanced JSON options" link:
https://docs.cloud.oracle.com/iaas/Content/API/SDKDocs/cliusing.htm#AdvancedJSON
Options.
To confirm the transfer, display the list of transfer jobs in the new compartment. See Listing
Transfer Jobs for more information.
Note
You can only use the CLI command to verify upload user
credentials.
You can verify the current upload user credentials to see if there are any problems or updates
required. If any configuration file is incorrect or invalid, the upload fails.
To verify the upload user credentials of a transfer job using the CLI
dts job verify-upload-user-credentials --bucket <bucket>
For example:
dts job verify-upload-user-credentials --bucket MyBucket1
Depending on your user configuration, you may get an error message returned similar to the
following:
ERROR : key_file /root/.oci/oci_api_key.pem is not a valid file
Typically, you would delete a transfer job early in the transfer process and before you create
any transfer packages or their associated disks. For example, you initiated the data transfer
by creating a transfer job, but changed your mind. If you want to delete a transfer job later in
the transfer process, you must first delete all transfer packages and their associated disks
from the transfer job.
Alternatively, you can delete a transfer job from the View Details page.
4. Confirm the deletion when prompted.
For example:
dts job delete --job-id ocid1.datatransferjob.oc1..exampleuniqueID
Confirm the deletion when prompted. The transfer job is deleted with no further action or
return. To confirm the deletion, display the list of transfer jobs in the compartment. See
Listing Transfer Jobs for more information.
Typically, you would close a transfer job when no further transfer job activity is required or
possible. Closing a transfer job requires that the status of all associated transfer packages be
returned, canceled, or deleted. In addition, the status of all associated transfer disks must be
complete, in error, missing, canceled, or deleted.
For example:
dts job close --job-id ocid1.datatransferjob.oc1..exampleuniqueID
Transfer Job :
ID : ocid1.datatransferjob.oc1..exampleuniqueID
CompartmentId : ocid.compartment.oc1..exampleuniqueID
UploadBucket : MyBucket1
Name : MyDiskImportJob
Label : JZM9PAVWH
CreationDate : 2019/06/04 17:07:05 EDT
Status : CLOSED
freeformTags : *** none ***
definedTags : *** none ***
Packages : [*** none ***]
UnattachedDevices : [*** none ***]
Appliances : [*** none ***]
Transfer Disks
Important
Note
For example:
/mnt/orcdts_DJZNWK3ET
When you register a transfer disk, Oracle Cloud Infrastructure generates a strong encryption
passphrase that is used to encrypt the transfer disk. This passphrase is displayed in the return
when you run the command. Create a local, secure copy of the encryption passphrase so you
can reference the passphrase again. You cannot retrieve the passphrase after it is shown
here. This passphrase is used to encrypt this disk and normally will not be needed again.
However, if the system is restarted before all files are copied to the filesystem and the disk is
then finalized through this CLI, you will need to provide the passphrase.
Creating a transfer disk requires the job ID returned from when you created the transfer job
and the path to the attached disk (for example /dev/sdb).
When the run the disk create command, the CLI displays information regarding the creation of
the disk, and prompts you to continue in several places. When the disk is created the following
disk information is displayed:
Important
Note
For example:
dts disk show --job-id ocid1.datatransferjob.oci1..exampleuniqueID --disk-label DNKZQ1XKC
Transfer Disk :
Label: : DNKZQ1XKC
SerialNumber: : VB6fc3b4a1-5d90f001
UploadStatusLogUrl : JVPWPQV6U/DNKZQ1XKC/upload_summary.txt
Status : PREPARING
The path syntax for the upload status log URL is <transfer_job_label>/<disk_
lable>/upload_summary.txt.
Note
Typically, you would delete a transfer disk during the disk preparation process. You created,
attached, and copied data to the transfer disk, but have changed your mind about shipping the
disk. If you want to reuse the disk, remove all file systems and create the disk again.
For example:
dts disk delete --job-id ocid1.datatransferjob.oci1..exampleuniqueID --disk-label DNKZQ1XKC
Note
If you shipped a disk to Oracle, but have changed your mind about uploading the files, you can
cancel the transfer disk.
Oracle cannot process canceled transfer disks. Oracle returns canceled transfer disks to the
sender.
For example:
dts disk cancel --job-id ocid1.datatransferjob.oci1..exampleuniqueID --disk-label DNKZQ1XKC
Note
Locking a transfer disk safely unmounts the disk and removes the encryption passphrase from
the Data Host.
For example:
dts disk lock --job-id ocid1.datatransferjob.oci1..exampleuniqueID --disk-label DNKZQ1XKC --block-device
/dev/sdb
If you need to unlock the transfer disk, you are prompted for the encryption passphrase that
was generated when you created the transfer disk.
For example:
dts disk unlock --job-id ocid1.datatransferjob.oci1..exampleuniqueID --disk-label DNKZQ1XKC --block-
device /dev/sdb --encryption-passphrase passphrase
Attach a transfer disk to a transfer package after you have done the following tasks in order:
Note
To attach a transfer disk to a transfer package using the Data Transfer Utility
dts disk attach --job-id <job_id> --package-label <package_label> --disk-label <disk_label>
For example:
dts attach --job-id ocid1.datatransferjob.oci1..exampleuniqueID --package-label PWA8O67MI --disk-label
DNKZQ1XKC
See Transfer Packages for more information, including how to obtain the package label.
To detach a transfer disk to a transfer package using the Data Transfer Utility
dts disk detach --job-id <job_id> --package-label <package_label> --disk-label <disk_label>
For example:
dts detach --job-id ocid1.datatransferjob.oci1..exampleuniqueID --package-label PWA8O67MI --disk-label
DNKZQ1XKC
You can query the transfer disk for information regarding the physical transfer disk such as
the loops, sizes, and mountpoints.
Note
You can only use the Data Transfer Utility to query the
transfer disk.
Transfer Packages
A transfer package is the virtual representation of the physical disk package that you are
shipping to Oracle for upload to Oracle Cloud Infrastructure.
Creating a transfer package requires the job ID returned from when you created the transfer
job. For example:
ocid1.datatransferjob.region1.phx..exampleuniqueID
The Data Transfer Package dialog appears displaying information such as the shipping
address, the shipping vendor, and the shipping status.
For example:
dts package create --job-id ocid1.datatransferjob.oci1..exampleuniqueID
Transfer Package :
Label : PWA8O67MI
TransferSiteShippingAddress : Oracle Data Transfer Service; Job:JZM9PAVWH Package:PWA8O67MI ; 21111
Ridgetop Circle; Dock B; Sterling, VA 20166; USA
DeliveryVendor : *** none ***
DeliveryTrackingNumber : *** none ***
ReturnDeliveryTrackingNumber : *** none ***
Status : PREPARING
Devices : [*** none ***]
To display the details of a transfer package using the Data Transfer Utility
dts package show --job-id <job_id> --package-label <package_label>
For example:
dts package show --job-id ocid1.datatransferjob.oci1..exampleuniqueID --package-label PWA8O67MI
Transfer Package :
Label : PWA8O67MI
TransferSiteShippingAddress : Oracle Data Transfer Service; Job:JZM9PAVWH Package:PWA8O67MI ; 21111
Ridgetop Circle; Dock B; Sterling, VA 20166; USA
DeliveryVendor : *** none ***
DeliveryTrackingNumber : *** none ***
ReturnDeliveryTrackingNumber : *** none ***
Status : PREPARING
Devices : [*** none ***]
Edit the transfer package and supply the tracking information when you ship the package.
6. Click Edit.
Typically, you would delete a transfer package early in the transfer process and before you
create its associated transfer disk. You initiated the transfer job and package, but have
changed your mind. If you delete a transfer package later in the transfer process, you must
first detach the associated transfer disk. You cannot delete a transfer package once the
package has been shipped to Oracle.
6. Click Edit.
Change the vendor and supply the tracking information as needed.
7. Click Edit Transfer Package.
For example:
dts package delete --job-id ocid1.datatransferjob.oci1..exampleuniqueID --package-label PWA8O67MI
If you shipped a transfer package, but have changed your mind about uploading the data, you
can cancel a transfer package. Before canceling a transfer package, you must first cancel the
transfer disk associated with that transfer package. Oracle cannot process canceled transfer
packages. Oracle returns canceled transfer packages to the sender.
For example:
dts package cancel --job-id ocid1.datatransferjob.oci1..exampleuniqueID --package-label PWA8O67MI
Storage bucket in your tenancy. You are then free to move the uploaded data to other Oracle
Cloud Infrastructure services as needed.
Note
The Data Transfer Appliance (import appliance) is a high-storage capacity device that is
specially prepared to copy and upload data to Oracle Cloud Infrastructure. You request an
import appliance from Oracle, copy your data onto it, and then ship it back to Oracle for
upload.
The command line interface (CLI) is a small footprint tool that you can use on its own or
with the Console to complete Oracle Cloud Infrastructure tasks, including Appliance-Based
Data Import jobs.
Note
HOST
A physical computer at the customer site on which one or more of the logical hosts
(Control, Data, Terminal Emulation) is running. Depending on your computing
environment, you can have any of the following:
All physical hosts much be on network used for the data transfer.
CONTROL HOST
The logical representation of the host computer at your site from which you perform Data
Transfer Service tasks. Depending on your needs, you may use one or more separate
hosts (Control and Data) to run your Appliance-Based Data Importjob.
Note
DATA HOST
The logical representation of the host computer on your site that stores the data you
intend to copy to Oracle Cloud Infrastructure.
Note
The logical representation of the host computer that uses terminal emulation software to
communicate with, and allow you to command, the import appliance.
BUCKET
The logical container in Oracle Cloud Infrastructure Object Storage where Oracle
operators upload your data. A bucket is associated with a single compartment in your
tenancy whose policies that determine what actions a user can perform on a bucket and
on all the objects in the bucket.
A new or existing IAM user that has the authorization and permissions to create and
manage transfer jobs.
A temporary IAM user that grants Oracle personnel the authorization and permissions to
upload the data from the import appliance to your designated Oracle Cloud Infrastructure
Object Storage bucket. Delete this temporary user after your data is uploaded to Oracle
Cloud Infrastructure.
Software running on the import appliance that provides management functions. Users
interact with this service though the Oracle Cloud Infrastructure CLI.
Appliance Specifications
Use NFS versions 3, 4, or 4.1 to copy your data onto the appliance. Here are some details
about the appliance:
- 10 GbE - SFP+
You are responsible for providing all network cables. If you
want to use SFP+, your transceivers must be compatible
with Intel X520 NICs.
- C13 - 14 power
- Frequency: 47–63 Hz
l Project Sponsor: Responsible for the overall success of the data transfer. Project
Sponsors usually have complete access to their organization's Oracle Cloud
Infrastructure tenancy. They coordinate with the other roles in the organization to
complete the implementation of data transfer project. The Project Sponsor is also
responsible for signing legal documentation and setting up notifications for the data
import.
l Infrastructure Engineer: Responsible for integrating the transfer appliance into the
organization's IT infrastructure from where the data is being transferred. Tasks
associated with this role include connecting the transfer appliance to power, placing it
within the network, and setting the IP address through a serial console menu using the
provided USB-to-Serial adapter.
l Data Administrator: Responsible for identifying and preparing the data to be
transferred to Oracle Cloud Infrastructure. This person usually has access to, and
expertise with, the data being migrated.
These roles correspond to the various phases of the data transfer described in the following
section. A specific role can be responsible for one or more phases.
l Appliances are shipped from Oracle to you with a tamper-evident security tie on the
transit case. A second tamper-evident security tie is included in the import appliance
transit case for you to secure the case when you ship the case back to Oracle. The
number on the physical security ties must match the numbers logged by Oracle in the
import appliance details.
l When you configure the import appliance for the first time:
o The import appliance generates a master AES-256 bit encryption key that is used
for all data written to or read from the device. The encryption key never leaves
the device.
o The encryption key is protected by an encryption passphrase that you must know
to access the encrypted data. The system securely fetches a provided encryption
passphrase from Oracle Cloud Infrastructure and registers that passphrase on the
import appliance.
Note
l After copying your data to a transfer appliance, the data transfer system generates a
manifest file. The manifest contains an index of all of the copied files and generated
data integrity hashes. The system also encrypts and copies the config_upload_user
configuration file to the transfer appliance. This configuration file describes the
temporary IAM data transfer upload user. Oracle uses the credentials and entries
defined in the config_upload_user file when processing the transfer appliance and
uploading files to Oracle Cloud Infrastructure Object Storage.
Note
Oracle cannot upload data from a transfer appliance without the correct credentials
defined in this configuration file. See Preparing Upload Configuration Files for more
information about the required configuration files.
l Oracle erases all of your data from the import appliance after it has been processed.
The erasure process follows the NIST 800-88 standards.
l Keep possession of the security tie after you have finished unpacking and connecting the
import appliance. Include it when returning the import appliance to Oracle. Failure to
include the security tie can result in a delay in the data migration process.
What's Next
You are now ready to prepare the host for the Appliance-Based Data Import. See Preparing
for Appliance Data Transfers for more information.
This topic describes the tasks associated with preparing for the Appliance-Based Data Import
job. The Project Sponsor role typically performs these tasks. See Roles and Responsibilities.
Note
Installing and Using the Oracle Cloud Infrastructure Command Line Interface
The Oracle Cloud Infrastructure Command Line Interface (CLI) provides a set of command
line-based tools for configuring and running Appliance-Based Data Import. Use the Oracle
Cloud Infrastructure CLI as an alternative to running commands from the Console. Sometimes
you must use the CLI to complete certain tasks as there is no Console equivalent.
The minimum CLI version required for Appliance-Based Data Import is 2.12.1.
DETERMINING CLI VERSIONS
Access the following URL to see the currently available version of the CLI:
https://github.com/oracle/oci-cli/blob/master/CHANGELOG.rst
Enter the following command at the prompt to see the version of the CLI currently installed on
your machine:
oci --version
If you have a version on your machine older than the version currently available, install the
latest version.
Note
Installation and configuration of the CLIs is described in detail in Command Line Interface
(CLI).
l --option <value> or
l --option=<value>
The following command to create a transfer job shows a typical CLI command construct.
Note
All CLI help commands have an associated help component you can access from the command
line. To view the help, enter any command followed by the --help or -h option. For example:
oci dts job --help
NAME
dts_job -
DESCRIPTION
Transfer disk or appliance job operations
AVAILABLE COMMANDS
o change-compartment
o close
o create
o delete
o detach-devices-details
...
When you run the help option (--help or -h) for a specified command, all the subordinate
commands and options for that level of CLI are displayed. If you want to access the CLI help
for a specific subordinate command, include it in the CLI string, for example:
oci dts job create --help
NAME
dts_job_create -
DESCRIPTION
Creates a new transfer disk or appliance job.
USAGE
oci dts job create [OPTIONS]
REQUIRED PARAMETERS
--bucket [text]
--compartment-id, -c [text]
Compartment OCID
--device-type [text]
Each service in Oracle Cloud Infrastructure integrates with IAM for authentication and
authorization.
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.
Access to resources is provided to groups using policies and then inherited by the users that
are assigned to those groups. Data transfer requires the creation of two distinct groups:
l Data transfer administrators who can create and manage transfer jobs.
l Data transfer upload users who can upload data to Object Storage. For your data
security, the permissions for upload users allow Oracle personnel to upload standard
and multi-part objects on your behalf and inspect bucket and object metadata. The
permissions do not allow Oracle personnel to inspect the actual data.
The Data Administrator is responsible for generating the required RSA keys needed for the
temporary upload users. These keys should never be shared between users.
l The data transfer administrator group requires an authorization policy that includes the
following:
Allow group <group_name> to manage data-transfer-jobs in compartment <compartment_name>
Alternatively, you can consolidate the manage buckets and manage objects policies
into the following:
Allow group <group_name> to manage object-family in compartment <compartment_name>
l The data transfer upload user group requires an authorization policy that includes the
following:
Allow group <group_name> to manage buckets in compartment <compartment_name> where all {
request.permission='BUCKET_READ', target.bucket.name='<bucket_name>' }
The Oracle Cloud Infrastructure administrator then adds a user to each of the data transfer
groups created. For details on creating users, see Managing Users.
Important
If your tenancy is not entitled to use the Data Transfer Appliance, you must request the Data
Transfer Appliance Entitlement before creating an appliance-based transfer job.
Use the following policy to enable users in a specific group to request a Data Transfer
Appliance Entitlement in your tenancy.
Allow group <group_name> to {DTA_ENTITLEMENT_CREATE} in tenancy
ENTITLEMENT ELIGIBILITY
Your request for a Data Transfer Appliance Entitlement in your tenancy may be denied if you
are a free trial customer. If your request is denied, upgrade to a full account. You can also
contact your Oracle Customer Support Manager or Oracle Support to determine your options
for obtaining the entitlement.
Once requested, the status of your request is visible at the top of the Transfer Job page. For
example:
It can take a while to get the Data Transfer Appliance Entitlement approved. After Oracle
receives your request, a Terms and Conditions Agreement is sent to the account owner via
DocuSign to use the appliance. The entitlement request is approved once the signature
is received. The Data Transfer Appliance Entitlement is a tenancy-wide entitlement that you
need to request once for each tenancy.
For example:
oci dts appliance request-entitlement --compartment-id ocid.compartment.oc1..exampleuniqueID --name
"John Doe" --email [email protected]
{
"data": {
"compartment-id": "ocid.compartment.oc1..exampleuniqueID",
"creation-time": "2019-12-18T18:29:15+00:00",
"defined-tags": {},
"display-name": null,
"freeform-tags": {},
"id": "ocid1.datatransferapplianceentitlement.oc1..exampleuniqueID",
"lifecycle-state": "CREATING",
"lifecycle-state-details": "REQUESTED",
"requestor-email": "[email protected]",
"requestor-name": "John Doe",
"update-time": "2019-12-20T19:04:09+00:00"
}
}
To show the status of a Data Transfer Appliance Entitlement request using the
CLI
oci dts appliance show-entitlement --compartment-id <compartment_id>
For example:
oci dts appliance show-entitlement --compartment-id ocid.compartment.oc1..exampleuniqueID
{
"data": {
"compartment-id": ""ocid.compartment.oc1..exampleuniqueID",
"defined-tags": null,
"display-name": null,
"freeform-tags": null,
"id": null,
"lifecycle-state": "ACTIVE",
"lifecycle-state-details": "APPROVED",
"requestor-email": "[email protected]",
"requestor-name": "John Doe"
}
}
The Object Storage service is used to upload your data to Oracle Cloud Infrastructure. Object
Storage stores objects in a container called a bucket within a compartment in your tenancy.
For details on creating the bucket to store uploaded data, see Managing Buckets.
Ensure that your local environment's firewall can communicate with the Data Transfer Service
running on the IP address ranges: 140.91.0.0/16. You also need to open access to the Object
Storage IP address ranges: 134.70.0.0/17.
This section describes how to create a transfer job as part of the preparation for the data
transfer. See Transfer Jobs for complete details on all tasks related to transfer jobs.
A transfer job represents the collection of files that you want to transfer and signals the
intention to upload those files to Oracle Cloud Infrastructure. Identify which compartment and
Object Storage bucket to which Oracle is to upload your data. Create the transfer job in the
same compartment as the upload bucket and supply a human-readable name for the transfer
job. Avoid entering confidential information when providing transfer job names.
Note
Creating a transfer job returns a transfer job ID that you specify in other transfer tasks. For
example:
ocid1.datatransferjob.region1.phx..<unique_ID>
Optionally, you can specify one or more free-form or defined tags when you create a transfer
job. For more information about tagging, see Resource Tags.
Note
Each transfer job you create has a unique ID within Oracle Cloud Infrastructure. For example:
ocid1.datatransferjob.oc1.phx.exampleuniqueID
You will need to forward this transfer job ID to the Data Administrator.
Tip
When you create a transfer job using the oci dts job
create CLI, the transfer job ID is displayed in the CLI's
return.
You can generate notifications that send messages regarding changes to a transfer job by
using the setup-notifications command through the CLI. Running this command creates a
topic, subscription for a list of email addresses, and a rule that notifies you on all events
related to the transfer job's activities and changes in state. This method provides a more
convenient way to generate notifications tailored to appliance-based transfer jobs.
Running the CLI command prompts you to enter the email addresses of each notification
subscriber as a comma separated list. Each recipient is sent an email with a link to confirm
they want to receive the notifications.
You can set up notifications when you create a transfer job using the CLI. You can also set up
notifications for existing transfer jobs.
The Project Sponsor is responsible for creating or obtaining configuration files that allow the
uploading of user data to the import appliance. Send these configuration files to the Data
Administrator where they can be placed in the Control Host (if there are separate Control and
Data Hosts).The config file is for the data transfer administrator, the IAM user with the
authorization and permissions to create and manage transfer jobs. The config_upload_user
file is for the data transfer upload user, the temporary IAM user that Oracle uses to upload
your data on your behalf.
Create a base Oracle Cloud Infrastructure directory and two configuration files with the
required credentials.
Create a Oracle Cloud Infrastructure directory (.oci) on the same Control Host machine
where the Oracle Cloud Infrastructure CLI is installed. For example:
mkdir /root/.oci/
The two configuration files (config and config_upload_user) are placed in what ever
location you choose.
Note
The data transfer administrator configuration file contains the required credentials for
working with Oracle Cloud Infrastructure. You can create this file using a setup CLI or
manually using a text editor.
Run the oci setup config command line utility to walk through the first-time setup process.
The command prompts you for the information required for the configuration file and the API
public/private keys. The setup dialog generates an API key pair and creates the configuration
file.
For more information about how to find the required information, see:
MANUAL SETUP
If you want to set up the API public/private keys yourself and write your own configuration
file, see SDK and Tool Configuration.
Tip
Create the data transfer administrator configuration file /root/.oci/config with the
following structure:
[DEFAULT]
user=<The OCID for the data transfer administrator>
fingerprint=<The fingerprint of the above user's public key>
key_file=<The _absolute_ path to the above user's private key file on the host machine>
tenancy=<The OCID for the tenancy that owns the data transfer job and bucket>
region=<The region where the transfer job and bucket should exist. Valid values are:
us-ashburn-1, us-phoenix-1, eu-frankfurt-1, and uk-london-1.>
For example:
[DEFAULT]
user=ocid1.user.oc1..<unique_ID>
fingerprint=4c:1a:6f:a1:5b:9e:58:45:f7:53:43:1f:51:0f:d8:45
key_file=/home/user/ocid1.user.oc1..exampleuniqueID.pem
tenancy=ocid1.tenancy.oc1..<unique_ID>
region=us-phoenix-1
For the data transfer administrator, you can create a single configuration file that contains
different profile sections with the credentials for multiple users. Then use the --profile
option to specify which profile to use in the command. Here is an example of a data transfer
administrator configuration file with different profile sections:
[DEFAULT]
user=ocid1.user.oc1..exampleuniqueID
fingerprint=4c:1a:6f:a1:5b:9e:58:45:f7:53:43:1f:51:0f:d8:45
key_file=/home/user/ocid1.user.oc1..exampleuniqueID.pem
tenancy=ocid1.tenancy.oc1..exampleuniqueID
region=us-phoenix-1
[PROFILE1]
user=ocid1.user.oc1..exampleuniqueID
fingerprint=4c:1a:6f:a1:5b:9e:58:45:f7:53:43:1f:51:0f:d8:45
key_file=/home/user/ocid1.user.oc1..exampleuniqueID.pem
tenancy=ocid1.tenancy.oc1..exampleuniqueID
region=us-ashburn-1
By default, the DEFAULT profile is used for all CLI commands. For example:
oci dts job create --compartment-id ocid.compartment.oc1..exampleuniqueID --bucket MyBucket --display-
name MyDisplay --device-type appliance
Instead, you can issue any CLI command with the --profile option to specify a different data
transfer administrator profile. For example:
oci dts job create --compartment-id ocid.compartment.oc1..exampleuniqueID --bucket MyBucket --display-
name MyDisplay --device-type appliance --profile MyProfile
Using the example configuration file above, the <profile_name> would be profile1.
If you created two separate configuration files, use the following command to specify the
configuration file to use:
oci dts job create --compartment-id <compartment_id> --bucket <bucket_name> --display-name <display_
name>
The config_upload_user configuration file is for the data transfer upload user, the
temporary IAM user that Oracle uses to upload your data on your behalf. Create this
configuration file with the following structure:
[DEFAULT]
user=<The OCID for the data transfer upload user>
Include the line endpoint=<url> for the Object Storage API endpoint in the upload user
configuration file.
For example:
endpoint=https://objectstorage.us-phoenix-1.oraclecloud.com
A complete configuration including the Object Storage endpoint might look like this:
[DEFAULT]
user=ocid1.user.oc1..exampleuniqueID
fingerprint=4c:1a:6f:a1:5b:9e:58:45:f7:53:43:1f:51:0f:d8:45
key_file=/home/user/ocid1.user.oc1..exampleuniqueID.pem
tenancy=ocid1.tenancy.oc1..exampleuniqueID
region=us-phoenix-1
endpoint=https://objectstorage.us-phoenix-1.oraclecloud.com
Important
The following table lists the basic entries that are required for each configuration file and
where to get the information for each entry.
Note
fingerprint Fingerprint for the key pair being used. To get Yes
the value, see Required Keys and OCIDs.
You can verify the data transfer upload user credentials using the following command:
oci dts job verify-upload-user-credentials --bucket <bucket_name>
This section describes how to request an import appliance from Oracle for copying your data
to Oracle Cloud Infrastructure See Import Appliances for complete details on all tasks related
to transfer jobs.
Oracle Cloud Infrastructure customers can use import appliances to migrate data for free. You
are only charged for Object Storage usage once the data is successfully transferred to your
designated bucket. All appliance requests still require approval from Oracle.
Tip
When you submit an appliance request, Oracle generates a unique label (name) to identify the
import appliance and your request is sent to Oracle for approval and processing.
You can generate notifications that send messages regarding changes to your import
appliance request by using the setup-notifications command through the CLI. Running this
command creates a topic, subscription for list of email addresses, and also a rule that notifies
you on all events related to the import appliance request's activities and changes in state. This
method provides a more convenient way to generate notifications tailored to import appliance
requests.
Running the CLI command prompts you to enter the email addresses of each notification
subscriber as a comma separated list. Each recipient is sent an email with a link to confirm
they want to receive the notifications.
Note
When you have completed all the tasks in this topic, provide the Data Administrator of the
following:
What's Next
You are now ready to configure your system for the data transfer. See Configuring Appliance
Data Imports.
This topic describes the tasks associated with configuring the Appliance-Based Data Import.
The Infrastructure Engineer role typically performs these tasks. See Roles and
Responsibilities.
When the shipping vendor delivers your import appliance, Oracle updates the status as
Delivered and provides the date and time the appliance was received in the Transfer
Appliance Details.
Important
Here are the tasks involved in unpacking and getting your import appliance ready to
configure.
Warning
2. Remove and compare the number on the security tie with the number logged by Oracle.
To see the security tie number logged by Oracle using the Console
a. Open the navigation menu. Under Core Infrastructure, go to Object Storage
and click Data Transfer - Imports.
b. Find the transfer job and import appliance associated with the removed security
tie.
d. Look at the contents of the Send Security Tie ID field in the Transfer
Appliance Details and compare that number with the number on the physical
tag.
To see the security tie number logged by Oracle using the CLI
At the command prompt on the Control Host, run oci dts appliance show to delete an
import appliance.
oci dts appliance show --job-id <job_id> --appliance-label <appliance_label>
Warning
Note
3. Open the transit case and ensure that the case contains the following items:
l Appliance unit and power cable (two types of power cables provided: C14 and C13
to 14)
l USB to DB-9 serial cable
l Return shipping instructions (retain these instructions)
l Return shipping label, label sleeve, tie-on tag, and zip tie
l Return shipment tamper-evident security tie (use this tie to ensure secure transit
case back to Oracle)
4. Compare the number on the return shipment security tie with the number logged by
Oracle.
To see the security tie number logged by Oracle using the Console
a. Open the navigation menu. Under Core Infrastructure, go to Object Storage
and click Data Transfer - Imports.
b. Find the transfer job and import appliance associated with the return shipment
security tie.
d. Look at the contents of the Return Security Tie ID field in the Transfer
Appliance Details and compare that number with the number on the physical
tag.
To see the security tie number logged by Oracle using the CLI
At the command prompt on the Control Host, run oci dts appliance show to the
security tie number associated with the import appliance.
oci dts appliance show --job-id <job_id> --appliance-label <appliance_label>
Warning
5. Remove the import appliance from the case and place the appliance on a solid surface
or in a rack.
Warning
6. Connect the appliance to your local network using one of the following:
l 10GBase-T: Standard RJ-45
l SFP+: The transceiver must be compatible with Intel X520 NICs.
7. Attach one of the provided power cords to the appliance and plug the other end into a
grounded power source.
8. Turn on the appliance by flipping the power switch on the back of the appliance.
Connect the import appliance to your designated Terminal Emulation Host computer using the
provided USB to DB-9 serial cable.
Note
Appliance-based transfers require you to set up your host for terminal emulation so you can
communicate with the appliance through the appliance's serial console. This communication
requires installing serial console terminal emulator software. We recommend using the
following:
Note
When the import appliance boots up, an appliance serial console configuration menu is
displayed on the Terminal Emulation Host to which the appliance is connected.
Oracle Cloud Data Transfer Appliance
- For use with minimum dts version: dts-0.4.140
- See "Help" for determining your dts version
1) Configure Networking
2) Show Networking
3) Reset Authentication
4) Show Authentication
5) Show Status
6) Collect Appliance Diagnostic Information
7) Generate support bundle
8) Shutdown Appliance
9) Reboot Appliance
10) Help
Select a command:
Note
The appliance supports a single active network interface on any of the 10-Gbps network ports.
If only one interface is cabled and active, that interface is chosen automatically. When
multiple interfaces are active, you are given the choice to select the interface to use.
Address: 10.0.0.1
Subnet Mask Length: 24
Gateway: 10.0.0.1
Enabling enp0s3
Now trying to restart the network
When you configure a network interface, the appliance software generates a new client access
token and appliance X.509/SSL certificate. The access token is used to authorize your Control
Host to communicate with the Data Transfer Appliance's Management Service. The x.509/SSL
certificate is used to encrypt communications with the Data Transfer Appliance's Management
Service over the network. Provide the access token and SSL certificate fingerprint values
displayed here when you use the CLI commands to initialize authentication on your host
machine.
You can change the selected interface, network information, and reset the authentication
material at any time by selecting Configure Networking again from the appliance serial
console menu.
After completing the tasks in this topic, send the following import appliance information to the
Data Administrator:
l Appliance IP address
l Access token
l SSL certificate fingerprint
What's Next
You are now ready to load your data to the disk. See Copying Data to the Import Appliance.
This topic describes the tasks associated with copying data from the Data Host to the import
appliance using the Control Host. The Data Administrator role typically performs these tasks.
See Roles and Responsibilities.
Note
Information Prerequisites
Before performing any import appliance copying tasks, you must obtain the following
information:
You might need to set up an HTTP proxy environment on the Control Host to allow access to
the public internet. This proxy environment allows the Oracle Cloud Infrastructure CLI to
communicate with the Data Transfer Appliance Management Service and the import appliance
over a local network connection. If your environment requires internet-aware applications to
use network proxies, configure the Control Host to use your environment's network proxies by
setting the standard Linux environment variables on your Control Host.
If you configured a proxy on the Control Host and the appliance is directly connected to that
host, the Control Host tries unsuccessfully to communicate with the appliance using a proxy.
Set a no_proxy environment variable for the appliance. For example, if the appliance is on a
local network at 10.0.0.1, you would set the following environment variable:
export NO_PROXY=10.0.0.1
If you have a restrictive firewall in the environment where you are using the Oracle Cloud
Infrastructure CLI, you may need to open your firewall configuration to the following IP
address ranges: 140.91.0.0/16.
Note
Initialize authentication to allow the host machine to communicate with the import appliance.
Use the values returned from the Configure Networking command. See Configuring the
Transfer Appliance Networking for details.
At the command prompt on the host, run oci dts physical-appliance initialize-
authentication to initialize authentication.
oci dts physical-appliance initialize-authentication --job-id <job-id> --appliance-cert-fingerprint
<fingerprint> --appliance-ip <ip_address> --appliance-label <appliance-label>
For example:
oci dts physical-appliance initialize-authentication --job-id
ocid1.datatransferjob.region1.phx..exampleuniqueID --appliance-cert-fingerprint
F7:1B:D0:45:DA:04:0C:07:1E:B2:23:82:E1:CA:1A:E9 --appliance-ip 10.0.0.1 --appliance-label XA8XM27EVH
When prompted, supply the access token and system. For example:
oci dts physical-appliance initialize-authentication --appliance-certfingerprint
86:CA:90:9E:AE:3F:0E:76:E8:B4:E8:41:2F:A4:2C:38 --applianceip 10.0.0.5 --jobid
ocid1.datatransferjob.oc1..exampleuniqueID --appliance-label XAKKJAO9KT
The Control Host can now communicate with the import appliance.
To show the status of and storage details about the connected import
appliance using the CLI
At the command prompt on the host, run oci dts physical-appliance show to show the
status of the connected import appliance.
oci dts physical-appliance show
For example:
Appliance Info :
encryptionConfigured : false
lockStatus : NA
finalizeStatus : NA
totalSpace : Unknown
availableSpace : Unknown
Configure the import appliance to use encryption. Oracle Cloud Infrastructure creates a strong
passphrase for each appliance. The command securely collects the strong passphrase from
Oracle Cloud Infrastructure and sends that passphrase to the Data Transfer service.
If your environment requires Internet-aware applications to use network proxies, ensure that
you set up the required Linux environment variables. See for more information.
Important
Note
For example:
oci dts physical-appliance configure-encryption --job-id
ocid1.datatransferjob.region1.phx..exampleuniqueID --appliance-label XA8XM27EVH
You must unlock the appliance before you can write data to it. Unlocking the appliance
requires the strong passphrase that is created by Oracle Cloud Infrastructure for each
appliance. Unlocking can be accomplished in two different ways:
l If you provide the --job-id and --appliance-label when running the unlock
command, the data transfer system retrieves the passphrase from Oracle Cloud
Infrastructure and sends it to the appliance during the unlock operation.
l You can query Oracle Cloud Infrastructure for the passphrase and provide that
passphrase when prompted during the unlock operation.
Important
To retrieve the passphrase to unlock the import appliance using the CLI
At the command prompt on the host, run dts physical-appliance unlock with --job-id
and --appliance-label to unlock the appliance.
oci dts physical-appliance unlock --job-id <job_id> --appliance-label <label>
For example:
oci dts physical-appliance unlock --job-id ocid1.datatransferjob.region1.phx..exampleuniqueID --
appliance-label XA8XM27EVH
Then, run dts physical-appliance unlock without --job-id and --appliance-label and
supply the passphrase when prompted.
oci dts physical-appliance unlock
A dataset is a collection of files that are treated similarly. You can write up to 100 million files
onto the import appliance for migration to Oracle Cloud Infrastructure. We currently support
one dataset per appliance. Appliance-Based Data Import supports NFS versions 3, 4, and 4.1
to write data to the appliance. In preparation for writing data, create and configure a dataset
to write to. See Datasets for complete details on all tasks related to datasets.
For example:
oci dts nfs-dataset create --name nfs-ds-1
For example:
oci dts nfs-dataset set-export --name nfs-ds-1 --rw true --world true
Here is another example of creating the export to give read/write access to a subnet:
oci dts nfs-dataset set-export --name nfs-ds-1 --ip 10.0.0.0 --subnet-mask-length 24 --rw true --world
false
Activation creates the NFS export, making the dataset accessible to NFS clients.
For example:
oci dts nfs-dataset activate --name nfs-ds-1
Note
l For Oracle Linux or Red Hat Linux, install the nfs-utils package. For example:
sudo yum install nfs-utils
For example:
mkdir -p /mnt/nfs-ds-1
For example:
Note
After the NFS share is mounted, you can write data to the share.
You can only copy regular files to transfer appliances. You cannot copy special files, such as
symbolic links, device special, sockets, and pipes, directly to the Data Transfer Appliance.
To transfer special files, create a tar archive of these files and copy the tar archive to the Data
Transfer Appliance. We recommend copying many small files using a tar archive. Copying a
single compressed archive file should also take less time than running copy commands such
as cp -r or rsync.
Here are some examples of creating a tar archive and getting it onto the Data Transfer
Appliance:
l Running a command to create a file with md5sum hashes for each file in addition to the
tar archive:
tar cvzf /mnt/nfs-dts-1/filesystem.tgz filesystem/ |xargs -I '{}' sh -c "test -f '{}' && md5sum '
{}'"|tee tarzip_md5
The tar archive file filesystem.tgz has a base64 md5sum once it is uploaded to OCI
Object Storage. Store the tarzip_md5 file where you can retrieve it. After the
compressed tar archive file is downloaded from Object Storage and unpacked, you can
compare the individual files against the hashes in the file.
To verify object data integrity of files uploaded to Object Storage from the Data Transfer
Appliance, a cryptographic hash using MD5 is provided for all objects uploaded to Object
Storage from the Data Transfer Appliance. Oracle Cloud Infrastructure provides the object
hash value in base64 encoding.
To download files imported into Object Storage and verify their integrity, run the following CLI
command:
oci os object get --namespace <object_storage_namespace> --bucket-name <bucket_name> --name <object_
name> --file <file_location>
For example:
oci os object get --namespace MyNamespace --bucket-name MyBucket1 --name JLA12B3C/XAABC12EFG/upload_
summary.txt –file upload_summary.txt
Open the file and match the file names of the uploaded files with the MD5 column:
For example:
oci os object get --namespace example_namespace --bucket-name bucket-1 --name file_1.txt –file file_
1.txt
Covert the base64 encoded hash value to hexadecimal, use the following command:
For example:
python -c 'print "EoN8s6dgT/9pGYA7Yx1klQ==".decode("base64").encode("hex")'
12837cb3a7604fff6919803b631d6495
Now generate the md5sum on Linux and verify both values match:
md5sum <file_name>
For example:
md5sum file_1.txt
12837cb3a7604fff6919803b631d6495 file_1.txt
Large files are split into 1 GB parts when they are uploaded from the Data Transfer Appliance
to Object Storage. You can verify the md5sum after downloading a file that was transferred in
multiple parts using one of several available scripts. See the following for more information
and links to these scripts:
https://github.com/oracle/oci-cli/issues/134
Note
After you are done writing data, deactivate the dataset. Deactivation removes the NFS export
on the dataset, disallowing any further writes.
For example:
oci dts nfs-dataset deactivate --name nfs-ds-1
Sealing a dataset stops all writes to the dataset. This process can take some time to
complete, depending upon the number of files and total amount of data copied to the import
appliance.
If you issue the seal command without the --wait option, the seal operation is triggered and
runs in the background. You are returned to the command prompt and can use the seal-
status command to monitor the sealing status. Running the seal command with the --wait
option results in the seal operation being triggered and continues to provide status updates
until sealing completion.
Important
The sealing operation generates a manifest across all files in the dataset. The manifest
contains an index of the copied files and generated data integrity hashes.
At the command prompt on the host, run oci dts nfs-dataset seal to seal the NFS
dataset.
oci dts nfs-dataset seal --name <dataset_name> [--wait]
For example:
oci dts nfs-dataset seal --name nfs-ds-1
Seal initiated. Please use seal-status command to get progress.
At the command prompt on the host, run oci dts nfs-dataset seal-status to monitor the
dataset sealing process.
oci dts nfs-dataset seal-status --name <dataset_name>
For example:
oci dts nfs-dataset seal-status --name nfs-ds-1
{
"data": {
"bytesProcessed": 2803515612507,
"bytesToProcess": 2803515612507,
"completed": true,
"endTimeInMs": 1591990408804,
"failureReason": null,
"numFilesProcessed": 182,
"numFilesToProcess": 182,
"startTimeInMs": 1591987136180,
"success": true
}
}
Note
After sealing the dataset, you can optionally download the dataset's seal manifest to a user-
specified location. The manifest file contains the checksum details of all the files. The transfer
site uploader consults the manifest file to determine the list of files to upload to object
storage. For every uploaded file, it validates that the checksum reported by object storage
matches the checksum in manifest. This validation ensures that no files got corrupted in
transit.
For example:
oci dts nfs-dataset get-seal-manifest --name nfs-ds-1 --output-file ~/Downloads/seal-manifest
Note
The credentials, API key, and bucket are required for Oracle to be able to upload your data to
Oracle Cloud Infrastructure Object Storage. When you finalize an appliance, you can no longer
access the appliance for dataset operations unless you unlock the appliance. See Reopening a
Dataset if you need to unlock an appliance that was finalized.
Important
For example:
oci dts physical-appliance finalize --job-id ocid1.datatransferjob.region1.phx..exampleuniqueID --
appliance-label XA8XM27EVH
Note
What's Next
You are now ready to ship your import appliance with the copied data to Oracle. See Shipping
the Import Appliance.
This topic describes the tasks associated with shipping the import appliance containing the
copied data to Oracle. The Infrastructure Engineer role typically performs these tasks. See
Roles and Responsibilities.
Note
Shut down the import appliance before packing up and shipping the appliance back to Oracle.
Important
Return the import appliance to Oracle within 30 days. If you need the appliance beyond the
standard 30-day window, you can file a Service Request (SR) to ask for an extension of up to
60 days.
Important
Warning
5. Close and secure the transit case with the return tamper-evident security tie.
6. Loop the top of the plastic tie-on tag with return shipping label through the handle of the
transit case. Remove the protective tape from the back of the tie-on tag, exposing the
adhesive area on which to secure the tag onto itself. Use the provided zip tie to secure
the tie-on tag to the handle.
7. Return the transit case to FedEx by doing one of the following:
l Drop off the packed, sealed, and labeled transit case to an FedEx Authorized
ShipCenter location or a nearby FedEx Office location. Obtain a receipt from the
vendor to certify transfer of custody.
l Schedule a pickup with FedEx at your location. Ensure that the transit case is
packed, sealed, and labeled before FedEx arrives for pickup.
The shipping vendor notifies Oracle when the appliance is shipped back to Oracle for
upload to Oracle Cloud Infrastructure Object Storage.
What's Next
Now you can track your return import appliance shipment to Oracle and review post transfer
logs and summaries. See Monitoring the Import Appliance and Data Transfer.
This topic describes the monitoring tasks to do after sending the import appliance with the
copied data back to Oracle for data transfer to Oracle Cloud Infrastructure. The Project
Sponsor role typically performs these tasks. See Roles and Responsibilities.
Note
The shipping vendor notifies Oracle when your import appliance is picked up and shipped back
for upload to Oracle Cloud Infrastructure Object Storage.
To monitor the status of your import appliance return shipment using the
Console
1. Open the navigation menu. Under Core Infrastructure, go to Object Storage and
click Data Transfer - Imports.
2. Find the transfer job and associated import appliance that you shipped back to Oracle
for data upload.
3. Under Transfer Appliances, look at the Status field.
Here are the import appliance status values, listed in alphabetic order:
CANCELLED
You can change your mind about uploading your data to Oracle Cloud Infrastructure Object
Storage and cancel your import appliance. Ship the appliance back to Oracle and then
cancel the appliance. Oracle always uses secure wipe tools on the boot and data areas
whenever an appliance is returned.
COMPLETE
Oracle completed your import appliance data upload. Your data is available in your
designated bucket in Oracle Cloud Infrastructure Object Storage.
CUSTOMER LOST
You have not returned the import appliance within the required 90 days.
DELIVERED
Oracle received a delivery confirmation from the shipping vendor that your import
appliance was delivered. When the appliance is delivered, Oracle provides the date and
time it was received in the appliance details. Appliance usage tracking begins.
ERROR
ORACLE PREPARING
Oracle approved your import appliance request. The status displays "Preparing" until the
appliance is shipped to you.
ORACLE RECEIVED
Oracle received your import appliance shipment. The status displays "Oracle Received"
until Oracle begins processing and uploading your data from the appliance.
You canceled your import appliance after you shipped the appliance back to Oracle. Oracle
received your canceled appliance does not upload any data from it.
PREPARING
You activated your import appliance. You can now copy your data onto the appliance. The
status displays "Preparing" until you ship the appliance back to Oracle.
PROCESSING
Oracle is processing and uploading the data from your import appliance. The status
displays "Processing"until Oracle completes uploading your data from the appliance.
REJECTED
Important
REQUESTED
You successfully completed your request for an import appliance. The status displays
requested until Oracle approves your appliance request.
RETURN SHIPPED
Oracle received confirmation from the shipping vendor that you shipped your import
appliance back to Oracle. The status displays "Return Shipped" until Oracle receives your
appliance.
You canceled your import appliance after the appliance was delivered to you or after you
shipped the appliance back to Oracle. Oracle received confirmation from the shipping
vendor that your canceled transfer appliance is on the way back to Oracle. The status
displays "Return shipped cancelled" until Oracle receives your appliance.
SHIPPING
Oracle completed the necessary preparations and shipped your import appliance. When
the appliance is shipped, Oracle provides the serial number of the appliance, the shipping
vendor, and the tracking number in the appliance details. The status displays shipping
until the appliance is delivered to you.
Oracle creates upload summary log files for each uploaded appliance. These log files are
placed in the bucket where data was uploaded to Oracle Cloud Infrastructure. The upload
summary file compares the appliance's manifest file to the contents of the target Oracle Cloud
Infrastructure Object Storage bucket after file upload.
Note
The top of the log report summarizes the overall file processing status:
P - Present: The file is present in both the device and the target bucket
M - Missing: The file is present in the device but not the target bucket. It was likely uploaded and
then deleted by another user before the summary was generated.
C - Name Collision: The file is present in the manifest but a file with the same name but different
contents is present in the target bucket.
U - Unreadable: The file is not readable from the disk
N - Name Too Long: The file name on disk is too long and could not be uploaded
If you upload more than 100,000 files, the upload details are broken into multiple pages. You
can only download the first page from the Console. Download the rest of the pages directly
from the Object Storage bucket. The subsequent pages have the same object name as the
first page, but have an enumerated suffix.
After the import appliance with your copied data is received by Oracle and the data transfer
begins, you can view the metrics associated with the transfer job in the Transfer Appliance
Details page in chart or table format.
Tip
Select the Start Time and End Time for these measures, either by manually entering the
days and times in their respective fields, or by selecting the Calendar feature and picking the
times that way. As an alternative to selecting a start and end time, you can also select from a
list of standard times (last hour, last 6 hours, and so forth) from the Quick Selects list for
the period measured. The time period you specify applies to all the measures.
Specify the Interval (for example, 5 minutes, 1 hour) that each measure is recorded from
the list.
Specify the Statistic being recorded (for example, Sum, Mean) for each measure from the
list.
Tip
Choose additional actions from the Options list, including viewing the query in the Metrics
Explorer, capturing the URL for the measure, and switching between chart and table view.
Click Reset Charts to delete any existing information in the charts and begin recording new
metrics.
See Monitoring Overview for general information on monitoring your Oracle Cloud
Infrastructure services.
Close the transfer job when no further transfer job activity is required or possible. Closing a
transfer job requires that the status of all associated import appliances be returned, canceled,
or deleted.
What's Next
You have completed the process of setting up, running, and monitoring the Appliance-Based
Data Import. If you determine that another appliance-based data transfers is required, repeat
the procedure from the beginning.
Transfer Jobs
A transfer job is the logical representation of a data migration to Oracle Cloud Infrastructure.
A transfer job is associated with one or more import appliances.
Note
Create the transfer job in the same compartment as the upload bucket and supply a human-
readable name for the transfer job. Avoid entering confidential information when providing
transfer job names.
Creating a transfer job returns a job OCID that you specify in other transfer tasks. For
example:
ocid1.datatransferjob.oci1..exampleuniqueID
For example:
oci dts job create --bucket MyBucket1 --compartment-id ocid.compartment.oc1..exampleuniqueID --display-
name MyApplianceImportJob --device-type appliance
{
"data": {
"attached-transfer-appliance-labels": [],
"attached-transfer-device-labels": [],
"attached-transfer-package-labels": [],
"compartment-id": "ocid.compartment.oc1..exampleuniqueID",
"creation-time": "2019-12-18T19:43:58+00:00",
"defined-tags": {},
"device-type": "APPLIANCE",
"display-name": "MyApplianceImportJob",
"freeform-tags": {},
"id": "ocid1.datatransferjob.oc1..exampleuniqueID",
"label": "JAKQVAGJF",
"lifecycle-state": "INITIATED",
"upload-bucket-name": "MyBucket1"
},
"etag": "2--gzip"
}
Optionally, you can specify one or more free-form or defined tags when you create a transfer
job. For more information about tagging, see Resource Tags.
oci dts job create --bucket <bucket> --compartment-id <compartment_id> --display-name <display_name> -
-device-type appliance --defined-tags '{ "<tag_namespace>": { "<tag_key>":"<value>" }}'
For example:
oci dts job create --bucket MyBucket1 --compartment-id ocid.compartment.oc1..exampleuniqueID --display-
name MyApplianceImportJob --device-type appliance --defined-tags '{"Operations": {"CostCenter": "01"}}'
{
"data": {
"attached-transfer-appliance-labels": [],
"attached-transfer-device-labels": [],
"attached-transfer-package-labels": [],
"compartment-id": "ocid.compartment.oc1..exampleuniqueID",
"creation-time": "2019-12-18T19:43:58+00:00",
"defined-tags": {
"operations": {
"costcenter": "01"
}
},
"device-type": "APPLIANCE",
"display-name": "MyApplianceImportJob",
"freeform-tags": {},
"id": "ocid1.datatransferjob.oc1..exampleuniqueID",
"label": "JAKQVAGJF",
"lifecycle-state": "INITIATED",
"upload-bucket-name": "MyBucket1"
},
"etag": "2--gzip"
}
For example:
oci dts job create --bucket MyBucket1 --compartment-id ocid.compartment.oc1..exampleuniqueID --display-
name MyApplianceImportJob --device-type appliance --freeform-tags '{"Pittsburg_Team":"brochures"}'
{
"data": {
"attached-transfer-appliance-labels": [],
"attached-transfer-device-labels": [],
"attached-transfer-package-labels": [],
"compartment-id": "ocid.compartment.oc1..exampleuniqueID",
"creation-time": "2019-12-18T19:43:58+00:00",
"defined-tags": {},
"device-type": "APPLIANCE",
"display-name": "MyApplianceImportJob",
"freeform-tags": {
"Pittsburg_Team": "brochures"
},
"id": "ocid1.datatransferjob.oc1..exampleuniqueID",
"label": "JAKQVAGJF",
"lifecycle-state": "INITIATED",
"upload-bucket-name": "MyBucket1"
},
"etag": "2--gzip"
}
Note
For example:
oci dts job list --compartment-id ocid.compartment.oc1..exampleuniqueID
{
"data": [
{
"creation-time": "2019-12-18T19:43:58+00:00",
"defined-tags": {},
"device-type": "APPLIANCE",
"display-name": "MyApplianceImportJob",
"freeform-tags": {},
"id": "ocid1.datatransferjob.oc1..exampleuniqueID",
"label": "JAKQVAGJF",
"lifecycle-state": "INITIATED",
"upload-bucket-name": "MyBucket1"
},
{
"creation-time": "2019-10-03T16:52:26+00:00",
"defined-tags": {},
"device-type": "DISK",
"display-name": "MyDiskImportJob",
"freeform-tags": {},
"id": "ocid1.datatransferjob.oc1..exampleuniqueID",
"label": "J2AWEOL5T",
"lifecycle-state": "INITIATED",
"upload-bucket-name": "MyBucket2"
}
]
}
When you use the CLI to list jobs, tagging details are also included in the output if you
specified tags.
For example:
oci dts job show --job-id ocid1.datatransferjob.oc1..exampleuniqueID
{
"data": {
"attached-transfer-appliance-labels": [],
"attached-transfer-device-labels": [],
"attached-transfer-package-labels": [],
"compartment-id": "ocid.compartment.oc1..exampleuniqueID",
"creation-time": "2019-12-18T19:43:58+00:00",
"defined-tags": {},
"device-type": "APPLIANCE",
"display-name": "MyApplianceImportJob",
"freeform-tags": {},
"id": "ocid1.datatransferjob.oc1..exampleuniqueID",
"label": "JAKQVAGJF",
"lifecycle-state": "INITIATED",
"upload-bucket-name": "MyBucket1"
},
"etag": "2--gzip"
}
When you use the CLI command to display the details of a job, tagging details are also
included in the output if you specified tags.
You are returned to the Details page for that transfer job.
For example:
{
"data": {
"attached-transfer-appliance-labels": [],
"attached-transfer-device-labels": [],
"attached-transfer-package-labels": [],
"compartment-id": "ocid.compartment.oc1..exampleuniqueID",
"creation-time": "2019-12-18T19:43:58+00:00",
"defined-tags": {},
"device-type": "APPLIANCE",
"display-name": "MyRenamedJob",
"freeform-tags": {},
"id": "ocid1.datatransferjob.oc1..exampleuniqueID",
"label": "JAKQVAGJF",
"lifecycle-state": "INITIATED",
"upload-bucket-name": "MyBucket1"
},
"etag": "3"
}
To edit the tags associated with a transfer job using the CLI
The CLI command replaces any existing tags with the new key/value pairs you specify. For
more information about tagging, see Resource Tags.
For example:
oci dts job update --job-id ocid1.datatransferjob.oc1..exampleuniqueID --defined-tags '{"Operations":
{"CostCenter": "42"}}'
{
"data": {
"attached-transfer-appliance-labels": [],
"attached-transfer-device-labels": [],
"attached-transfer-package-labels": [],
"compartment-id": "ocid.compartment.oc1..exampleuniqueID",
"creation-time": "2019-12-18T19:43:58+00:00",
"defined-tags": {
"operations": {
"costcenter": "42"
}
},
"device-type": "APPLIANCE",
"display-name": "MyApplianceImportJob",
"freeform-tags": {},
"id": "ocid1.datatransferjob.oc1..exampleuniqueID",
"label": "JAKQVAGJF",
"lifecycle-state": "INITIATED",
"upload-bucket-name": "MyBucket1"
},
"etag": "2--gzip"
}
For example:
oci dts job update --job-id ocid1.datatransferjob.oc1..exampleuniqueID --freeform-tags '{"Chicago_
Team":"marketing_videos"}'
{
"data": {
"attached-transfer-appliance-labels": [],
"attached-transfer-device-labels": [],
"attached-transfer-package-labels": [],
"compartment-id": "ocid.compartment.oc1..exampleuniqueID",
"creation-time": "2019-12-18T19:43:58+00:00",
"defined-tags": {},
"device-type": "APPLIANCE",
"display-name": "MyApplianceImportJob",
"freeform-tags": {
"Chicago_Team": "marketing_videos"
},
"id": "ocid1.datatransferjob.oc1..exampleuniqueID",
"label": "JAKQVAGJF",
"lifecycle-state": "INITIATED",
"upload-bucket-name": "MyBucket1"
},
"etag": "2--gzip"
}
To edit or delete the tags associated with a transfer job using the CLI
The CLI command replaces any existing tags with the new key/value pairs you specify. If you
want to delete some of the tags, specify a new tag string that does not contain the unwanted
key/value pairs.
Partial tag deletion is handled in the same way as you edit tags:
You are returned to the Details page for that transfer job.
<compartment_id> is the compartment to which the data transfer job is being moved.
<options> are:
l --if-match: The tag that must be matched for the task to occur for that entity. If set,
the update is only successful if the object's tag matches the tag specified in the request.
l --from-json: Provide input to this command as a JSON document from a file using the
file://path-to/file syntax. The --generate-full-command-json-input option can be
used to generate a sample JSON file to be used with this command option. The key
names are pre-populated and match the command option names (converted to
camelCase format, e.g. compartment-id --> compartmentId), while the values of the
keys need to be populated by the user before using the sample file as an input to this
command. For any command option that accepts multiple values, the value of the key
can be a JSON array. Options can still be provided on the command line. If an option
exists in both the JSON document and the command line then the command line
specified value will be used. For examples on usage of this option, please see our "using
CLI with advanced JSON options" link:
https://docs.cloud.oracle.com/iaas/Content/API/SDKDocs/cliusing.htm#AdvancedJSON
Options.
For example:
oci dts job move --job-id ocid1.datatransferjob.oc1..exampleuniqueID compartment-id
ocid.compartment.oc1..exampleuniqueID
To confirm the transfer, display the list of transfer jobs in the new compartment. See Listing
Transfer Jobs for more information.
Note
You can only use the CLI command to verify upload user
credentials.
You can verify the current upload user credentials to see whether there are any problems or
updates required. If any configuration file is incorrect or invalid, the upload fails.
To verify the upload user credentials of a transfer job using the CLI
oci dts job verify-upload-user-credentials --bucket <bucket>
For example:
oci dts job verify-upload-user-credentials --bucket MyBucket1
Depending on your user configuration, you may get an error message returned similar to the
following:
WARNING: Permissions on /home/user/.oci/config_upload_user are too open.
To fix this please try executing the following command:
+Config Errors+-----------+-----------------------------------------------------------------------------
-----+
| Key | Error | Hint
|
+-------------+-----------+-----------------------------------------------------------------------------
-----+
| fingerprint | malformed | openssl rsa -pubout -outform DER -in path to your private key | openssl md5
-c |
+-------------+-----------+-----------------------------------------------------------------------------
-----+
You can delete transfer jobs when they are in the Initiated, Preparing, and Close states.
For example:
oci dts job delete --job-id ocid1.datatransferjob.oc1..exampleuniqueID
Confirm the deletion when prompted. The transfer job is deleted with no further action or
return. To confirm the deletion, display the list of transfer jobs in the compartment. See
Listing Transfer Jobs for more information.
Typically, you would close a transfer job when no further transfer job activity is required or
possible. Closing a transfer job requires that the status of all associated transfer packages be
returned, canceled, or deleted. In addition, the status of all associated transfer disks must be
complete, in error, missing, canceled, or deleted.
When you close the transfer job, the status changes to Closed.
For example:
oci dts job close --job-id ocid1.datatransferjob.oc1..exampleuniqueID
{
"data": {
"attached-transfer-appliance-labels": [],
"attached-transfer-device-labels": [],
"attached-transfer-package-labels": [],
"compartment-id": "ocid.compartment.oc1..exampleuniqueID",
"creation-time": "2020-05-20T22:00:43+00:00",
"defined-tags": {},
"device-type": "APPLIANCE",
"display-name": "MyApplianceImportJob",
"freeform-tags": {},
"id": "ocid1.datatransferjob.oc1..exampleuniqueID",
"label": "JGX4N1XLI",
"lifecycle-state": "CLOSED",
"upload-bucket-name": "MyBucket"
},
"etag": "1"
}
Import Appliances
This section describes tasks associated with the Oracle-provided import appliance.
REQUESTING APPLIANCES
Tip
Choose the transfer job for which you want to request an import appliance.
2. Under Transfer Appliances, click Request Transfer Appliance.
The Request Transfer Appliance dialog appears.
3. Enter the shipping address details where you want the import appliance sent.
l Company Name: Required. Specify the name of the company that owns the data
being migrated to Oracle Cloud Infrastructure.
l Recipient Name: Required. Specify the name of the recipient who receives the
import appliance.
l Recipient Phone Number: Required. Specify the recipient's phone number.
l Recipient Email Address: Required. Specify the recipient's email address.
l Care Of: Optional intermediary party responsible for transferring the import
appliance shipment from the delivery vendor to the intended recipient.
l Address Line 1: Required. Specify the street address where the import
appliance is being sent.
l Address Line 2: Optional identifying address details like building, suite, unit, or
floor information.
l City/Locality: Required. Specify the city or locality.
l State/Province/Region: Required. Specify the state, province, or region.
l Zip/Postal Code: Specify the zip code or postal code.
l Country: Required. Select the country.
4. Click Request Transfer Appliance.
<options> are:
For example:
oci dts appliance request --job-id ocid1.datatransferjob.oc1..exampleuniqueID --addressee MyCompany --
care-of "John Doe" --address1 "123 Main Street" --city-or-locality Anytown --state-province-region NY --
country USA --zip-postal-code 12345 --phone-number 8005551212 --email [email protected]
{
"data": {
"appliance-delivery-tracking-number": null,
"appliance-delivery-vendor": null,
"appliance-return-delivery-tracking-number": null,
"creation-time": "2020-05-20T22:08:13+00:00",
"customer-received-time": null,
"customer-returned-time": null,
"customer-shipping-address": {
"address1": "123 Main Street",
"address2": null,
"address3": null,
"address4": null,
"addressee": "MyCompany",
"care-of": "John Doe",
"city-or-locality": "Anytown",
"country": "USA",
"email": "[email protected]",
"phone-number": "3115551212",
"state-or-region": "NY",
"zipcode": "12345"
},
"delivery-security-tie-id": null,
"label": "XAKWEGKZ5T",
"lifecycle-state": "REQUESTED",
"next-billing-time": null,
"return-security-tie-id": null,
"serial-number": null,
"transfer-job-id": "ocid1.datatransferjob.oc1..exampleuniqueID",
"upload-status-log-uri": "JAKQVAGJF/XAKWEGKZ5T/upload_summary.txt"
}
}
When you submit an appliance request, Oracle generates a unique label (label":
"XAKWEGKZ5T) to identify the import appliance and your request is sent to Oracle for approval
and processing.
The time it takes to approve, prepare, and ship your appliance request varies and depends on
various factors, including current available inventory. Oracle provides status updates daily
throughout the appliance request and ship process.
3. Find and select the transfer job for which you want to monitor associated appliance
requests.
4. Under Transfer Appliances, find the appliance label Oracle assigned to your appliance
request and look at the Status field.
Here are the key status values to look for when monitoring your appliance request:
l Requested: You successfully completed your request for an import appliance. The
status displays Requested until Oracle approves your appliance request.
l Rejected: Oracle denied your appliance request.
Important
l Oracle Preparing: Oracle approved your appliance request. The status displays
Oracle Preparing until the import appliance is shipped to you.
l Shipping: Oracle completed the necessary preparations and shipped your import
appliance. When the import appliance is shipped, Oracle provides the serial number of
the import appliance, the shipping vendor, and the tracking number in the Transfer
Appliance Details. The status displays Shipping until the import appliance is
delivered to you.
l Delivered: The shipping vendor delivered your import appliance. When the import
appliance is delivered, Oracle provides the date and time the import appliance was
received in the Transfer Appliance Details. The status displays Delivered.
For example:
oci dts appliance show --job-id ocid1.datatransferjob.oc1..exampleuniqueID --appliance-label XAKWEGKZ5T
{
"data": {
"appliance-delivery-tracking-number": null,
"appliance-delivery-vendor": null,
"appliance-return-delivery-tracking-number": null,
"creation-time": "2020-05-20T22:08:13+00:00",
"customer-received-time": null,
"customer-returned-time": null,
"customer-shipping-address": {
"address1": "123 Main Street",
"address2": null,
"address3": null,
"address4": null,
"addressee": "MyCompany",
"care-of": "John Doe",
"city-or-locality": "Anytown",
"country": "USA",
"email": "[email protected]",
"phone-number": "3115551212",
"state-or-region": "NY",
"zipcode": "12345"
},
"delivery-security-tie-id": null,
"label": "XAKWEGKZ5T",
"lifecycle-state": "REQUESTED",
"next-billing-time": null,
"return-security-tie-id": null,
"serial-number": null,
"transfer-job-id": "ocid1.datatransferjob.oc1..exampleuniqueID",
"upload-status-log-uri": "JAKQVAGJF/XAKWEGKZ5T/upload_summary.txt"
}
}
For example:
oci dts appliance list --job-id ocid1.datatransferjob.oc1..exampleuniqueID
{
"data": {
"transfer-appliance-objects": [
{
"creation-time": "2020-05-20T22:08:13+00:00",
"label": "XAKWEGKZ5T",
"lifecycle-state": "PROCESSING",
"serial-number": null
}
]
}
}
For example:
oci dts appliance show --job-id ocid1.datatransferjob.oc1..exampleuniqueID --appliance-label XAKWEGKZ5T
{
"data": {
"appliance-delivery-tracking-number": null,
"appliance-delivery-vendor": null,
"appliance-return-delivery-tracking-number": null,
"creation-time": "2020-05-20T22:08:13+00:00",
"customer-received-time": null,
"customer-returned-time": null,
"customer-shipping-address": {
"address1": "123 Main Street",
"address2": null,
"address3": null,
"address4": null,
"addressee": "MyCompany",
"care-of": "John Doe",
"city-or-locality": "Anytown",
"country": "USA",
"email": "[email protected]",
"phone-number": "3115551212",
"state-or-region": "NY",
"zipcode": "12345"
},
"delivery-security-tie-id": null,
"label": "XAKWEGKZ5T",
"lifecycle-state": "PROCESSING",
"next-billing-time": null,
"return-security-tie-id": null,
"serial-number": null,
"transfer-job-id": "ocid1.datatransferjob.oc1..exampleuniqueID",
"upload-status-log-uri": "JAKQVAGJF/XAKWEGKZ5T/upload_summary.txt"
}
}
You can only edit the shipping information when the status is Requested.
<changed_fields> represents one or more of the following shipping address fields that you
want to update:
--care-of <care_of> --address1 <address> --city <city> --state <addressee> --zip <zip> --country
<country> --phone-number <phone_number> email <email>
You only need to include those fields that are being updated. For example:
oci dts appliance update-shipping-address --job-id ocid1.datatransferjob.oc1..exampleuniqueID --
appliance-label XAKWEGKZ5T --addressee MyCompany --care-of "Richard Roe" --phone-number 3115559876 --
email [email protected]
Confirm the update of the appliance request shipping information when prompted. The
appliance details are displayed with the updated information.
{
"data": {
"appliance-delivery-tracking-number": null,
"appliance-delivery-vendor": null,
"appliance-return-delivery-tracking-number": null,
"creation-time": "2020-05-20T22:08:13+00:00",
"customer-received-time": null,
"customer-returned-time": null,
"customer-shipping-address": {
"address1": "123 Main Street",
"address2": null,
"address3": null,
"address4": null,
"addressee": "MyCompany",
"care-of": "Richard Roe",
"city-or-locality": "Anytown",
"country": "USA",
"email": "[email protected]",
"phone-number": "3115559876",
"state-or-region": "NY",
"zipcode": "12345"
},
"delivery-security-tie-id": null,
"label": "XAKWEGKZ5T",
"lifecycle-state": "REQUESTED",
"next-billing-time": null,
"return-security-tie-id": null,
"serial-number": null,
"transfer-job-id": "ocid1.datatransferjob.oc1..exampleuniqueID",
"upload-status-log-uri": "JAKQVAGJF/XAKWEGKZ5T/upload_summary.txt"
}
}
You can delete an appliance request before Oracle approves the request—the status must be
Requested. For example, you initiated the transfer by creating a transfer job and requested
an appliance, but changed your mind.
For example:
oci dts appliance delete --job-id ocid1.datatransferjob.oc1..exampleuniqueID --appliance-label
XAKWEGKZ5T
You can display a list of all appliances registered through the initialize authentication
command. See Initializing Authentication to the Appliance for more information.
Note
You can only use the CLI command to display a list of all
appliances registered through the initialize
authentication command.
For example:
oci dts physical-appliance list
{
"data": [
{
"appliance_profile": "DEFAULT",
"endpoint": "https://10.20.20.7"
}
]
}
UNREGISTERING APPLIANCES
You can unregister an appliance previously registered through the initialize authentication
command. See Initializing Authentication to the Appliance for more information.
Configure the import appliance to use encryption. Oracle Cloud Infrastructure creates a strong
passphrase for each appliance. The command securely collects the strong passphrase from
Oracle Cloud Infrastructure and sends that passphrase to the Data Transfer service.
If your environment requires Internet-aware applications to use network proxies, ensure that
you set up the required Linux environment variables. See for more information.
Important
Note
For example:
Note
Initialize authentication to allow the host machine to communicate with the import appliance.
Use the values returned from the Configure Networking command. See Configuring the
Transfer Appliance Networking for details.
For example:
oci dts physical-appliance initialize-authentication --job-id ocid1.datatransferjob.oc1..exampleuniqueID
--appliance-cert-fingerprint F7:1B:D0:45:DA:04:0C:07:1E:B2:23:82:E1:CA:1A:E9 --appliance-ip 10.0.0.1 --
appliance-label XAKWEGKZ5T
When prompted, supply the access token and system. The Control Host can now communicate
with the import appliance.
Datasets
A dataset is a collection of files that are treated similarly. You can write up to 100 million files
onto the appliance for import. We currently support one dataset per appliance.
Note
CREATING DATASETS
Appliance data transfer supports NFS version 3, 4, and 4.1 to write data to the import
appliance. In preparation for writing data, create and configure a dataset to write to.
For example:
Activation creates the NFS export, making the dataset accessible to NFS clients.
For example:
oci dts nfs-dataset activate --name nfs-ds-1
For example:
oci dts nfs-dataset set-export --name nfs-ds-1 --rw true --world true
{
"data": {
"datasetType": "NFS",
"name": "nfs-ds-1",
"nfsExportDetails": {
"exportConfigs": [
{
"hostname": null,
"ipAddress": null,
"readWrite": true,
"subnetMaskLength": null,
"world": true
}
]
},
"state": "INITIALIZED"
}
}
Here is another example of creating the export to give read/write access to a subnet:
oci dts nfs-dataset set-export --name nfs-ds-1 --ip 10.0.0.0 --subnet-mask-length 24 --rw true --world
false
}
}
Note
After you are done writing data, deactivate the dataset. Deactivation removes the NFS export
on the dataset, disallowing any further writes.
For example:
dts nfs-dataset deactivate --name nfs-ds-1
Sealing a dataset stops all writes to the dataset. This process can take some time to
complete, depending upon the number of files and total amount of data copied to the import
appliance.
If you issue the seal command without the --wait option, the seal operation is triggered and
runs in the background. You are returned to the command prompt and can use the seal-
status command to monitor the sealing status. Running the seal command with the --wait
option results in the seal operation being triggered and continues to provide status updates
until sealing completion.
Important
The sealing operation generates a manifest across all files in the dataset. The manifest
contains an index of the copied files and generated data integrity hashes.
For example:
oci dts nfs-dataset seal --name nfs-ds-1
For example:
oci dts nfs-dataset seal-status --name nfs-ds-1
{
"data": {
"bytesProcessed": 2803515612507,
"bytesToProcess": 2803515612507,
"completed": true,
"endTimeInMs": 1591990408804,
"failureReason": null,
"numFilesProcessed": 182,
"numFilesToProcess": 182,
"startTimeInMs": 1591987136180,
"success": true
}
}
After sealing the dataset, you can optionally download the dataset's seal manifest to a user-
specified location. The manifest file contains the checksum details of all the files. The transfer
site uploader consults the manifest file to determine the list of files to upload to object
storage. For every uploaded file, it validates that the checksum reported by object storage
matches the checksum in manifest. This validation ensures that no files got corrupted in
transit.
For example:
oci dts nfs-dataset get-seal-manifest --name nfs-ds-1 --output-file ~/Downloads/seal-manifest
REOPENING A DATASET
If changes are necessary after sealing a dataset or finalizing an import appliance, you must
reopen the dataset to modify the contents. Make the required changes and again seal the
dataset. Resealing the dataset generates a new manifest.
Note
You must unlock the appliance before you can write data to it. Unlocking the appliance
requires the strong passphrase that is created by Oracle Cloud Infrastructure for each
appliance. Unlocking can be accomplished in two different ways:
l If you provide the --job-id and --appliance-label when running the unlock
command, the data transfer system retrieves the passphrase from Oracle Cloud
Infrastructure and sends it to the appliance during the unlock operation.
l You can query Oracle Cloud Infrastructure for the passphrase and provide that
passphrase when prompted during the unlock operation.
For example:
oci dts physical-appliance unlock --job-id ocid1.datatransferjob.oc1..exampleuniqueID --appliance-label
XAKWEGKZ5T
Retrieving the passphrase from Oracle Cloud Infrastructure
{
"data": {
"availableSpaceInBytes": "64.00GB",
"encryptionConfigured": true,
"finalizeStatus": "NOT_FINALIZED",
"lockStatus": "NOT_LOCKED",
"totalSpaceInBytes": "64.00GB"
}
}
For example:
{
"data": {
"encryption-passphrase": "passphrase"
}
}
Then, run dts physical-appliance unlock without --job-id and --appliance-label and
supply the passphrase when prompted.
oci dts physical-appliance unlock
Repeat the same tasks you performed when you originally wrote data to the import appliance
beginning with activating the dataset in the Copying Files to the NFS Share section.
Note
For example:
oci dts nfs-dataset list
Note
For example:
oci dts nfs-dataset show --name MyDataset
{
"data": {
"datasetType": "NFS",
"name": "nfs-ds-1",
"nfsExportDetails": {
"exportConfigs": [
{
"hostname": null,
"ipAddress": null,
"readWrite": true,
"subnetMaskLength": null,
"world": true
}
]
},
"state": "ACTIVE"
}
}
DELETING A DATASET
Note
For example:
oci dts nfs-dataset delete --name nfs-ds-1
Confirm the deletion when prompted. The dataset is deleted with no further action or return.
To confirm the deletion, display the list of datasets. See Displaying Dataset Lists for more
information.
Troubleshooting
This topic describes various troubleshooting issues related to the Data Transfer Service.
You can also use the log capture feature of the serial port emulator to capture the output.
Serial port emulators often support the ability to copy the session to a file. Refer to the
documentation of your serial port emulation package for instructions. Copying to a log file is
useful if you need assistance from Oracle or if your emulation session does not allow you to
scroll back and see all the output.
For each operation, the display shows exactly what command was executed and all the
options.
Any problem with the diagnostic data collection results in the console output being written to
the log file of the service. Failure of the commands is indicative of a serious problem, perhaps
requiring the return of the appliance. Here is an example of the log:
Mar 6 17:55:33 localhost console-diags: {"Module": "main", "Type": "Info", "Message": "Received message
{\"cmd\": \"collect\"}"}
Mar 6 17:55:33 localhost console-diags: {"Module": "main", "Type": "Info", "Message": "Setting up output
Seal Status :
success : false
failureReason :
Number of special files : 5
startTime : 2019/03/26 11:52:37 PDT
endTime : 2019/03/26 11:52:39 PDT
numFilesToProcess : 0
numFilesProcessed : 0
bytesToProcess : 0.00 KB
bytesProcessed : 0.00 KB
bytesToProcess : 0.00 KB
Then run find to get the full list of all special files and the specific type of each one.
find <mountpoint> \! -type f \! -type d | xargs file
For example:
$ find /mnt/nfs-ds-1 \! -type f \! -type d | xargs file
/mnt/nfs-ds-1/myfile1: symbolic link to `/home/user1/myfile1'
/mnt/nfs-ds-1/myfile2: symbolic link to `/home/user1/myfile2'
Next, review the list and remove all special files from the NFS mount point.
find <mountpoint> \! -type f \! -type d | xargs rm
Monitor the seal progress. Wait for it to complete successfully and continue with the
subsequent steps.
If a failure occurs, run the following command to verify appliance IP and the path to
appliance.
ping -I <local_interface> <appliance_ip>
To determine expected interface, run ip route or an equivalent command. Verify that routing
table is sane. Try running traceroute if you're not sure to see the network path to the
appliance IP.
You should receive the response "Not found." This failure can indicate the IP address may be
wrong. For example, nothing is listening on port 443.If you receive a failure message, run the
following command:
openssl s_client -showcerts -connect <appliance_ip>:443
You should see a certificate issued for "Oracle Cloud Infrastructure" / "Data Transfer
Appliance."
This command is similar to curl but does not use HTTPS and so proxies do not affect it. If this
command works, and curl fails, then verify there are no proxy environmental variables.
l ~/.oci/config and
l ~/.oci/config_upload_user
Both files must have "[DEFAULT]" as the first line. Use of the "~" character in a path is not
valid in the file's contents.
Be sure that access to the disk is not done through any devicemapper or volume manager.
During the data transfer, the expectation is that the file system is created on a "raw" device.
You can confirm that the Data Transfer Utility has exclusive access by attempting to manually
format the disk being used for your data transfer. The Data Transfer Utility uses the
cryptsetup utility to create an encrypted device. You can run cryptsetup from the
command line (root privileges required):
cryptsetup luksFormat -c aes-xts-plain64 -s 512 -h sha512 --iter-time 2000 --use-random /dev/<sdXX>
<sdXX> is the name of the disk being used for the data transfer.
When prompted, respond that you do want to encrypt the device. You are required to provide
a passphrase. Any passphrase is acceptable as the cryptsetup utility can run on a disk
repeatedly without any problems.
If the command succeeds, then you know that the Data Transfer Utility can gain exclusive
ownership of the disk to do the necessary for the data transfer.
If this error occurs, activate the data set, mount it, and run the following find command on the
filesystem:
find . -print0 | perl -n0e 'chomp; print $_, "\n" if /[[:^ascii:][:cntrl:]]/'
than the one currently installed requires the following steps in order:
If you manually installed the CLI using pip, run the following command:
pip uninstall oci-cli
If you manually installed the CLI in a virtualenv, run the following command:
<virtualenv_path>/bin/pip uninstall oci-cli
See Manual Installation for installation instructions for your downloaded CLI version.
You can quickly provision an autonomous database or co-managed DB system. You have full
access to the features and operations available with the database, but Oracle owns and
manages the infrastructure.
You can also extend co-managed database services into your data center by using Exadata
Cloud@Customer, which applies the combined power of Exadata and Oracle Cloud
Infrastructure while enabling you to meet your organization's data-residency requirements.
For details about each offering, start with the following overview topics:
Autonomous Databases
The Database service offers Oracle's Autonomous Database with transaction processing and
data warehouse workload types.
Co-managed Systems
Note
Oracle Cloud Infrastructure supports a licensing model with two license types. With License
included, the cost of the cloud service includes a license for the Database service. With
Bring Your Own License (BYOL), Oracle Database customers can use existing licenses
with Oracle Cloud Infrastructure. Note that Oracle Database customers remain responsible for
complying with license restrictions applicable to their BYOL licenses, as defined in their
program order for those licenses.
You do not need separate on-premises licenses and cloud licenses. BYOL databases support all
advanced Database service manageability functionality, including backing up and restoring a
DB system, patching, and Oracle Data Guard.
You can choose BYOL when you launch a cloud-hosted Oracle Cloud Infrastructure database or
DB system. Choosing BYOL impacts how the usage data for the instance is metered and
subsequent billing. You can also switch license types after provisioning.
Note that on some provisioning dialogs in the Console, the BYOL option is labeled My
Organization Already Owns Oracle Database Software Licenses.
For additional information about license pricing and features, see Oracle Cloud Database
Services. For guidelines on using Oracle Database licenses, see Database Licensing.
You can switch license type after provisioning your resource. For information about switching
the license type, see the following:
Important
For more information about moving resources to other compartments, see Moving Resources
to a Different Compartment.
Monitoring Resources
You can monitor the health, capacity, and performance of your Oracle Cloud Infrastructure
resources by using metrics, alarms, and notifications. For more information, see Monitoring
Overview and Notifications Overview.
For information about available Database service metrics and how to view them, see
Database Metrics.
See Database for details about Database resources that emit events.
Resource Identifiers
Most types of Oracle Cloud Infrastructure resources have a unique, Oracle-assigned identifier
called an Oracle Cloud ID (OCID). For information about the OCID format and other ways to
identify your resources, see Resource Identifiers.
For more information on tenancies and compartments, see "Key Concepts and Terminology"
in the Oracle Cloud Infrastructure Getting Started Guide. For general information about using
the API, see REST APIs. For information on deprecated Database Service APIs, see
Deprecated Database Service APIs
If you're new to policies, see Getting Started with Policies and Common Policies. If you want
to write policies that provide stricter access to database resources, see Details for the
Database Service.
An administrator in your organization needs to set up groups, compartments, and policies that
control which users can access which services, which resources, and the type of access. For
example, the policies control who can create new users, create and manage the cloud
network, launch instances, create buckets, download objects, etc. For more information, see
Getting Started with Policies. For specific details about writing policies for each of the
different services, see Policy Reference.
If you’re a regular user (not an administrator) who needs to use the Oracle Cloud
Infrastructure resources that your company owns, contact your administrator to set up a user
ID for you. The administrator can confirm which compartment or compartments you should be
using.
For common policies used to authorize Oracle Cloud Infrastructure Database users, see
Common Policies.
For in-depth information on granting users permissions for the Database service, see Details
for the Database Service in the IAM policy reference.
Note
Autonomous Databases
o Autonomous Databases
o Autonomous Container Databases
o Autonomous Exadata Infrastructure instances
o Reboot node
o Soft reset of node
l Registering or deregistering an Autonomous Database with Data Safe.
Note
Exadata Databases
o Start node
o Stop node
o Reboot node
o Soft reset of node
and Autonomous Data Warehouse. You do not need to configure or manage any hardware, or
install any software. After provisioning, you can scale the number of CPU cores or the storage
capacity of the database at any time without impacting availability or performance.
Autonomous Database handles creating the database, as well as the following maintenance
tasks:
Upgrading a database
If your Autonomous Database instance is on Oracle Database 18c, after notifying you of the
upgrade date, Oracle will automatically upgrade your instance to Oracle Database 19c. If you
want to upgrade at a time of your choosing, then you can manually upgrade your database to
Oracle Database 19c. By choosing to manually upgrade, you can start using the Autonomous
Database features that are available in Oracle Database 19c prior to the automatic upgrade
date. See To upgrade an Autonomous Database for information on manual upgrades.
Always Free databases have only single available version. You can see the version that is
being used for your database in the details screen. After a newer Oracle Database version is
available in Oracle Cloud Infrastructure, your database will be automatically upgraded during
one of your database's upcoming maintenance windows.
To learn about Free Tier Databases, see Oracle Cloud Infrastructure Free Tier. To learn about
the details of the Always Free Autonomous Database, see Overview of the Always Free
Autonomous Database. To provision an Always Free Autonomous Database, see Creating an
Autonomous Database.
For information on regional availability of Always Free Autonomous Database, see the
"Always Free Cloud Services" section of Data Regions for Platform and Infrastructure
Services.
l The Autonomous Transaction Processing workload type configures the database for
a transactional workload, with a bias towards high volumes of random data access.
For a complete product overview of Autonomous Transaction Processing, see
Autonomous Transaction Processing. For Autonomous Transaction Processing tutorials,
see Quick Start tutorials.
l The Autonomous Data Warehouse workload type configures the database for a
decision support or data warehouse workload, with a bias towards large data scanning
operations.
For a complete product overview of Autonomous Data Warehouse, see Autonomous
Data Warehouse. For Autonomous Data Warehouse tutorials, see Quick Start tutorials.
Infrastructure Options
Autonomous Databases have the following Exadata infrastructure options:
l Dedicated Exadata Infrastructure: With this option, you have exclusive use of the
Exadata hardware. Dedicated Exadata infrastructure offers multitenant database
architecture, allowing you to create and manage multiple Autonomous Databases within
a single database system. Both workload types (transaction processing and
warehouse) can be provisioned on dedicated Exadata infrastructure. You have the
following hardware configuration options:
CPU Scaling
You can manually scale the database's base number of CPU cores up or down at any time.
Note the following:
Autonomous Database's auto scaling feature allows your database to use up to three times
the current base number of CPU cores at any time. As demand increases, auto scaling
automatically increases the number of cores in use. Likewise, as demand drops, auto scaling
automatically decreases the number of cores in use. Scaling takes place without any lag time,
and you are only billed for your actual average CPU core usage per hour. Note the following
points regarding the auto scaling feature:
l Auto scaling is enabled by default and can be enabled or disabled at any time.
l The auto scaling status for a database (enabled or disabled) is displayed on the
database details page.
l The base number of OCPU cores allocated to a database is guaranteed. For databases
on dedicated Exadata infrastructure, the maximum number of cores available to a
database depends on the total number of cores available in the Exadata infrastructure
instance, and is further limited by the number of free cores that aren't being used by
other auto scaling databases to meet high-load demands. Available OCPU cores are
enabled on a "first come, first served basis" for autoscaling databases sharing an
Autonomous Exadata Infrastructure instance.
The following table illustrates OCPU core availability for a single database on an X8 quarter
rack dedicated Exadata infrastructure instance. As you increase the database's base core
count from 1 to 40 cores, the maximum core count scales until it reaches the hardware limit
of 100 OCPUs. The final column, which shows the remaining available OCPUs that can be
allocated to additional databases, assumes that no other databases exist on the quarter rack
instance.
Example: OCPU auto scaling for a single database on an X8 quarter rack as base OCPU is increased
Base OCPU core count Maximum OCPU core count OCPU cores remaining
1 3 99
8 24 92
32 96 68
40 100 60
The following table illustrates OCPU core availability for four databases on an X8 half rack
dedicated Exadata infrastructure instance. The hardware limit is 200 OCPUs. The Base OCPU
count for each database is guaranteed to be available to the database at all times. In the
example, the three database with auto scaling enabled are in contention for the 60 available
cores that are not allocated to any database as base cores. Databases Sales and Development
each auto scaled to take a combined 140 OCPU, and database Chicago (with auto scaling
disabled) is using its 10 base OCPU. That leaves only 50 OCPU remaining in the half rack
hardware instance, and the base OCPU of database HR is 50. Therefore, database HR cannot
auto scale up until cores are released by the other auto scaling databases.
Development yes 20 60 40
Chicago no 10 10 10
HR yes 50 150 50
Storage Scaling
Autonomous Database allows you to scale the storage capacity of the database at any time
without impacting availability or performance.
Preview version software should not be used for production databases or for databases that
need to persist beyond the limited preview period. Note that preview databases and their
associated resources (including backups) are terminated automatically at the conclusion of
the preview period. Oracle will notify customers prior to the conclusion of the preview period
regarding the end date of the preview.
Any existing Autonomous Database (including those provisioned with preview version
software) can be cloned using a preview version of Autonomous Database. However, preview
version databases cannot be cloned using the regular (general-availability) Autonomous
Database software.
When multiple database versions are available, you choose an Oracle Database version when
you provision or clone a database.
Note
For information on current regional availability, see "Oracle Database Versions and
Availability by Region" in the Oracle Help Center: Autonomous Transaction Processing |
Autonomous Data Warehouse.
Regional Availability
Autonomous Database is currently available in all regions of the commercial realm.
Autonomous Database is currently not available in regions within the Government Cloud
realm.
Security Considerations
Oracle Data Safe is a unified cloud service control center that enables you to monitor the
security status of your Autonomous Databases on shared Exadata infrastructure and dedicated
Exadata infrastructure. It helps you to evaluate security controls, assess user security,
monitor user activity, and address data security compliance requirements for your database
by evaluating the sensitivity of your data as well as masking sensitive data for non-production
databases. It provides the following set of features in a single, easy-to-use management
console:
For information on registering or deregistering a database with Data Safe, see Managing an
Autonomous Database. Autonomous Databases using the private endpoint feature are not
compatible with Data Safe.
For information on creating and using Data Safe instances, see the Data Safe documentation.
Autonomous Database is one of the Oracle Cloud Infrastructure services that can be privately
accessed through a service gateway within a VCN. This means you do not need a public IP or
NAT to access your Autonomous Database instance from any of the cloud services within the
Oracle Services Network. For example, if you have a Compute instance that uses a VCN with a
service gateway, you can route traffic between your Compute instance and an Autonomous
Database in the same region without the traffic going over the internet. For information on
setting up a VCN service gateway and configuring it to access all supported Oracle Service
Network services (which include Autonomous Database), see Access to Oracle Services:
Service Gateway.
You can create an ACL during database provisioning, or at any time thereafter. You can also
edit an ACL at any time. Removing all entries from the list makes the database accessible to
all clients with the applicable credentials. See To manage the access control list of an
Autonomous Database on shared Exadata infrastructure to learn how to create, update, or
delete an ACL.
Important
Note the following about using an ACL with your Autonomous Database:
l When you restore a database the existing ACLs are not overwritten by the restore.
l The network ACL applies to the database connections and Oracle Machine Learning
notebooks. If an ACL is defined and you try to login to Oracle Machine Learning from a
client whose IP is not specified on the ACL you will see a "login rejected based on access
control list set by the administrator" error.
l Oracle Application Express (APEX), RESTful services, and SQL Developer Web are
subject to ACLs. You can create rules specifying Virtual Cloud Networks, Virtual Cloud
Network OCIDs, IP addresses, or CIDR blocks to control access to these tools.
l The Autonomous Database Service console is not subject to ACL rules.
l If you have a private subnet in your VCN that is configured to access the public internet
through an NAT gateway, you need to enter the public IP address of the NAT gateway in
your ACL definition. Clients in the private subnet do not have public IP addresses. See
NAT Gateway for more information.
Automatic Maintenance
For Autonomous Databases on shared Exadata infrastructure, Oracle manages the automatic
maintenance. You can view the next scheduled maintenance in the Console on the details page
for your Autonomous Database. For Autonomous Databases on dedicated Exadata
infrastructure, see Overview of Dedicated Exadata Infrastructure Maintenance.
For in-depth documentation on using and managing your Autonomous Transaction Processing
on dedicated Exadata infrastructure, see the following topics:
For known issues, see Known Issues for Oracle Autonomous Database on Dedicated Exadata
Infrastructure.
For in-depth documentation on using and managing your Autonomous Transaction Processing
database, see the following topics:
For information on using a database client to manage your database, see Connect
Autonomous Transaction Processing Using a Client Application.
For in-depth documentation on using and managing your Autonomous Data Warehouse
database, see the following topics:
For information on using a database client to manage your database, see the following topic:
The following table describes the recovery-time objectives and recovery-point objectives
(data loss tolerance) for service-level objectives.
High Availability Policy Recovery Time (RTO) and Recovery Point (RPO) Sevice-
level Objectives
l Data corruptions
l Full database failures
l Complete storage failures
l Availability domain or region
failures
In the preceding table, the amount of downtime for events requiring restoring from a backup
varies due to the nature of the failure. In the most optimistic case, a physical block corruption
is detected and the block is repaired with block media recovery in minutes. In this case, only
a small portion of the database is affected and there is zero data loss.
In a more pessimistic case, an availability domain or data region fails, and a new cluster must
be provisioned and restored with the latest database backup, including all archives, and a
complete database recovery must be run. Data loss is limited by the last successful archive
log backup, the frequency of which is every 15 minutes, by default, and includes a log switch
and subsequent archive log backup of any redo that has not been backed up to Oracle Cloud
Infrastructure Object Storage. The backup should be quick and estimated data loss can be less
than 15 minutes or, at worst, slightly above 15 minutes.
Ensure that network connectivity to Oracle Cloud Infrastructure is reliable so that you can
access your tenancy's Autonomous Database resources.
Follow the guidelines in the Continuous Availability - Application Continuity for the Oracle
Database white paper to experience application-level service uptime similar to that of the
database uptime.
If you want to provision an Always Free Autonomous Database, see the To create an Always
Free Autonomous Database task instructions in this topic. For more information on the Free
Tier, see Oracle Cloud Infrastructure Free Tier.
Prerequisites
l To create an Autonomous Database, 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. See
Authentication and Authorization for more information on user authorizations for the
Tip
Tip
Note
WORKLOAD TYPE
Select the desired workload type. See About Autonomous Transaction Processing and
About Autonomous Data Warehouse for information about each workload type.
INFRASTRUCTURE TYPE
l Always Free: Use this selector to show only Always Free configuration options if
you are provisioning an Always FreeAutonomous Database. See Overview of the
ADMINISTRATOR CREDENTIALS
Set the password for the Autonomous Database Admin user by entering a password that
meets the following criteria. You use this password when accessing the Autonomous
Database service console and when using an SQL client tool.
l Contains from 12 to 30 characters
l Contains at least one lowercase letter
l Contains at least one uppercase letter
l Contains at least one number
NETWORK ACCESS
Select the network access type. Important: you cannot change the network access type
after provisioning.
l Allow secure access from anywhere: This option provides access using a
public endpoint that you secure with an access control list (ACL). Use this option if
you need to access your database from the internet or your on-premises network.
o Virtual Cloud Network (OCID) allows you input the OCID of a VCN in a
text box. You can use this input method if the VCN you are specifying is in a
compartment which you do not have permission to access.
If you add a Virtual Cloud Network to your ACL, you can limit further by
specifying allowed VCN IP addresses or CIDR ranges. Enter those addresses or
CIDR blocks in the IP Addresses or CIDRs field that is displayed below your
Virtual Cloud Network choice. Use commas to separate your VCN addresses
and CIDR blocks in the input field. You can specify the following types of
IP addresses at the VCN level:
o Private IP addresses within your Oracle Cloud Infrastructure VCN
o Private IP addresses within an on-premises network that have access to
your Autonomous Database using a transit routing and a private connection
via FastConnect or VPN Connect.
Click + Another Entry to add additional access rules to your list.
l Virtual cloud network: This option creates a private endpoint for your database
within a specified VCN. See Autonomous Database with Private Endpoint for more
information.
o Subnet: The subnet to which the Autonomous Database should attach. Click
change compartment to select a subnet in a different compartment.
Important: You cannot change the specified subnet after provisioning. We
recommend that you specify a private subnet.
o Hostname prefix: Optional. This specifies a host name prefix for the
Autonomous Database and associates a DNS name with the database
instance, in the following form:
hostname_prefix.adb.region.oraclecloud.com
The host name must begin with an alphabetic character, and can contain
only alphanumeric characters and hyphens (-). You can use up to 63
alphanumeric characters for your hostname prefix.
If you choose not to specify a hostname prefix, Oracle creates a unique
DNS name for your database.
o Network security groups: You must specify at least one network
security group (NSG) for your Autonomous Database. NSGs function as
virtual firewalls, allowing you to apply a set of ingress and egress security
rules to your database. A maximum of five NSGs can be specified.
For more information on creating and working with NSGs, see Network
Security Groups.
Note that if you choose a subnet with a security list, the security rules for
the database will be a union of the rules in the security list and the NSGs.
Tip
LICENSE TYPE
Specify the license type setting you want to use. Your choice affects metering for billing.
You have the following options:
l Bring your own license: Bring my existing database software licenses to the
database cloud service.
l License included: Subscribe to new database software licenses and the
Database cloud service.
ADVANCED OPTIONS
Tags: Optionally, you can apply 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.Avoid entering confidential
information.
2. Click Create Autonomous Database.
Note
WHAT NEXT?
Note
WORKLOAD TYPE
Select the desired workload type. See About Autonomous Transaction Processing and
About Autonomous Data Warehouse for information about each workload type.
INFRASTRUCTURE TYPE
Select Dedicated Infrastructure.
ADMINISTRATOR CREDENTIALS
Set the password for the Autonomous Database Admin user by entering a password that
meets the following criteria. You use this password when accessing the Autonomous
Database service console and when using an SQL client tool.
l Contains from 12 to 30 characters
l Contains at least one lowercase letter
l Contains at least one uppercase letter
l Contains at least one number
l Does not contain the double quotation mark (")
l Does not contain the string "admin", regardless of casing
ADVANCED OPTIONS
Tags: Optionally, you can apply 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.Avoid entering confidential
information.
2. Click Create Autonomous Database.
Note
WHAT NEXT?
WORKLOAD TYPE
Select the desired workload type. See About Autonomous Transaction Processing and
About Autonomous Data Warehouse for information about each workload type.
INFRASTRUCTURE TYPE
l Always Free: Move this selector to the right so that the provisioning workflow
shows only the Always Free configuration options. Note that the Core CPU count
and Storage configuration fields are disabled when provisioning an Always Free
Autonomous Database. Your database will have 1 OCPU, 8 GB of memory, and
20 GB of storage.
ADMINISTRATOR CREDENTIALS
Set the password for the Autonomous Database Admin user by entering a password that
meets the following criteria. You use this password when accessing the Autonomous
Database service console and when using an SQL client tool.
l Contains from 12 to 30 characters
l Contains at least one lowercase letter
l Contains at least one uppercase letter
LICENSE TYPE
When you provision an Always Free Autonomous Database, the license type is set to
License included and cannot be adjusted.
ADVANCED OPTIONS
Tags: Optionally, you can apply 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.Avoid entering confidential
information.
2. Click Create Autonomous Database.
Note
WHAT NEXT?
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.
Prerequisites
To perform the management tasks in this topic, 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. See Authentication and
Authorization for more information on user authorizations for the Oracle Cloud Infrastructure
Database service.See Let database and fleet administrators manage Autonomous Databases
for sample Autonomous Database policies. See Details for the Database Service for detailed
information on policy syntax.
You can perform basic administrative tasks for Autonomous Databases in the Oracle Cloud
InfrastructureConsole including stopping, starting, and scaling your databases. You can also
use the Console to back up or to restore the database.
l Stopped
l Terminating
l Terminated
l Unavailable
Note
Tip
Warning
l With auto scaling enabled, the database can use up to three times more CPU and IO
resources than specified by the number of OCPUs currently shown in the Scale
Up/Down dialog. See CPU Scaling for more information.
l If auto scaling is disabled while more CPU cores are in use than the database's currently
assigned number of cores, then Autonomous Database scales the number of CPU cores
in use down to the assigned number.
l Enabling auto scaling does not change the concurrency and parallelism settings for the
predefined services. See Managing Concurrency and Priorities on Autonomous Data
Warehouse and Managing Priorities on Autonomous Transaction Processing for more
information.
l Is not one of the last four passwords used for the database
l Is not a password you previously set within the last 24 hours
6. Enter the password again in the Confirm Password field.
7. Click Update.
For information on using the Autonomous Transaction Processing service console features,
see Managing and Monitoring Performance of Autonomous Transaction Processing. For
information on using the Autonomous Data Warehouse service console features, see Managing
and Monitoring Performance of Autonomous Data Warehouse Cloud.
Note
If your Autonomous Database uses Oracle Database version 18c, after notifying you of the
upgrade date, Oracle automatically upgrades your instance to Oracle Database version 19c.
However, you do not need to wait until the automatic upgrade to view and test the new
features that are available in Oracle Database 19c. You can manually upgrade a paid database
at any time.
UPGRADE OPTIONS
When you run this upgrade, the Autonomous Database will be upgraded to the latest version
available in Oracle Cloud Infrastructure.
Important
database is available during the upgrade process, although some lifecycle management
functions are not available.
6. The database restarts automatically when the upgrade is complete. It is not available
while restarting.
Note
To upgrade your Autonomous Database from version 18c to 19c by creating a full clone:
5. When configuring the clone database, in the Choose database version list, select the
newer Oracle Database version.
ABOUT WALLETS
A upgraded Autonomous Database instance uses the same wallet after the upgrade is
complete. You can continue to use your existing instance and regional wallets to connect to
the database.
A database that was cloned has its own wallet. You cannot use the wallet of the source
database to connect to the clone. Obtain a new wallet for the clone and use it to access the
cloned database.
l Virtual cloud network: This option uses a private endpoint within a VCN in your
tenancy.
l Allow secure access from everywhere: This option uses a public endpoint provided
by Oracle.
This topic describes how to switch a database's network access to the Virtual cloud
network option. See Autonomous Database with Private Endpoint more information on this
option, including the prerequisites needed to switch.
Note
The host name must begin with an alphabetic character, and can contain only
alphanumeric characters and hyphens (-). You can use up to 63 alphanumeric
characters for your hostname prefix.
If you choose not to specify a hostname prefix, Oracle creates a unique
DNS name for your database.
l Network security groups: You must specify at least one network security
group (NSG) for your Autonomous Database. NSGs function as virtual firewalls,
allowing you to apply a set of ingress and egress security rules to your database.
A maximum of five NSGs can be specified.
For more information on creating and working with NSGs, see Network Security
Groups.
Note that if you choose a subnet with a security list, the security rules for the
database will be a union of the rules in the security list and the NSGs.
7. Click Update.
8. In the Confirm dialog, type the Autonomous Database name to confirm the change.
Click Update.
Notes:
l After updating the network access type all database users must obtain a new wallet and
use the new wallet to access the database. See About Downloading Client Credentials
(Wallets) for more information.
l If you had access control list (ACL) rules defined for the public endpoint, the rules do not
apply for the private endpoint.
3. In the list of Autonomous Databases, click the display name of the database you want to
administer. The Autonomous Database Details page displays.
4. In the Autonomous Database Information tab, the Network section displays the
names of your database's virtual cloud network (VCN), subnet, and network security
groups (NSGs). The following networking configuration changes are possible:
l Clicking the names of your VCN and subnet will take you to the resource details
pages of those resources. While you can edit the configurations of those
resources, you cannot assign a different VCN or subnet to your Autonomous
Database.
l You can add or remove NSGs by clicking the edit link by the listed NSGs in the
Network section on the Autonomous Database Details page. Note that your
specified NSGs must contain stateless security rules.
l You can edit the security rules of any of your Autonomous Database's NSGs by
clicking the name of the NSG. Clicking the name takes your to the Network
Security Group Details page of the NSG.
l Virtual cloud network: This option uses a private endpoint within a VCN in your
tenancy.
l Allow secure access from everywhere: This option uses a public endpoint provided
by Oracle.
This topic describes how to switch a database's network access to the Allow secure access
from everywhere option.
Note
Notes:
l After updating the network access type all database users must obtain a new wallet and
use the new wallet to access the database. See About Downloading Client Credentials
(Wallets) for more information.
l After the update completes, you can define access control rules for the public endpoint
by specifying ACLs. See To manage the access control list of an Autonomous Database
on shared Exadata infrastructure for more information. See Access Control Lists (ACLs)
for Databases on Shared Exadata Infrastructure for details and restrictions regarding
ACLs.
An access control list (ACL) provides additional protection for your Autonomous Database by
allowing only the IP addresses in the list to connect to the database. An ACL must contain at
least one entry representing an IP address or a range of addresses. To create or edit an
ACL for an existing database that uses shared Exadata infrastructure, do the following:
Note
You can specify the following types of addresses in your list by using the IP notation
type drop-down selector:
l IP Address allows you to specify one or more individual public IP address. Use
commas to separate your addresses in the input field.
l CIDR Block allows you to specify one or more ranges of public IP addresses
using CIDR notation. Use commas to separate your CIDR block entries in the input
field.
l Virtual Cloud Network allows you to specify an existing VCN. The drop-down
listing in the input field allows you to choose from the VCNs in your current
compartment for which you have access permissions. Click the Change
Compartment link to display the VCNs of a different compartment.
l Virtual Cloud Network (OCID) allows you input the OCID of a VCN in a text
box. You can use this input method if the VCN you are specifying is in a
compartment which you do not have permission to access.
If you add a Virtual Cloud Network to your ACL, you can limit further by specifying
allowed VCN IP addresses or CIDR ranges. Enter those addresses or CIDR blocks in the
IP Addresses or CIDRs field that is displayed below your Virtual Cloud Network
choice. Use commas to separate your VCN addresses and CIDR blocks in the input field.
You can specify the following types of IP addresses at the VCN level:
l Private IP addresses within your Oracle Cloud Infrastructure VCN
l Private IP addresses within an on-premises network that have access to your
Autonomous Database using a transit routing and a private connection via
FastConnect or VPN Connect.
Click + Another Entry to add additional access rules to your list.
Important
To remove the ACL, simply delete all entries in the list. This action allows all clients to
connect to the database.
6. Click Update.
If the Lifecycle State is Available when you click Update, the Lifecycle State changes to
Updating until the ACL update is complete. The database is still up and accessible, there is no
downtime. When the update is complete the Lifecycle State returns to Available and the
network ACL rules from the access control list are in effect.
For more information about access control lists, see Access Control Lists (ACLs) for Databases
on Shared Exadata Infrastructure.
specific work request, click the operation name. Then, select an option in the More
information section.
For associated resources, you can click the the Actions icon (three dots) next to a
resource to copy the resource's OCID.
Note
For information on network security management tasks, see Networking Management Tasks
in this topic.
Note
l Enable communication from the Data Safe private endpoint to your database. To do this,
update the security rules in network security groups or the security list of your VCN
configured with an Autonomous Database and Data Safe private endpoint. See the
Access and Security section in this manual for information about network security
groups, security rules, and security lists.
Note
l If the database uses dedicated Exadata infrastructure, enter the ADMIN password
and click Confirm to start the registration or deregistration process. The ADMIN
password is needed to unlock Data Safe so that it can monitor the database.
l If the database uses shared Exadata infrastructure, click Confirm to start the
registration or deregistration process.
5. You can optionally use either or both of the following to monitor the registration and
deregistration process:
l Use the work request created by the system to monitor the progress of the
registration or deregistration.
l Click View Console to display the Data Safe user interface for the registered
database. For information about using Data Safe, see the Data Safe
documentation.
When Database Vault is enabled on the database you are registering or deregistering,
complete the following additional steps to register or deregister the database. These are
needed to accommodate the additional database security provided by Database Vault.
l The Database Vault account manager must first grant specific access rights to the
ADMIN database user before they can register or deregister an Autonomous Database.
Otherwise, an "insufficient privileges" error is displayed.
l After the database has been registered or deregistered, the Database Vault account
manager can remove the access rights to limit access during normal operations,
l After the database registration is complete, the Database Vault owner must grant
specific access rights to the DS$ADMIN database user to enable normal operations. See
the Data Safe documentation to learn about the access rights needed.
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.
l ListAutonomousDatabases
l GetAutonomousDatabase
l UpdateAutonomousDatabase
l ChangeAutonomousDatabaseCompartment
l StartAutonomousDatabase
l RestartAutonomousDatabase
l StopAutonomousDatabase
l DeleteAutonomousDatabase
Tip
Applications and tools connect to Autonomous Databases by using Oracle Net Services (also
known as SQL*Net). SQL*Net supports a variety of connection types to Autonomous
Databases, including Oracle Call Interface (OCI), ODBC drivers, JDBC OC, and JDBC Thin
Driver.
To support connections of any type, you must download the client security credentials and
network configuration settings required to access your database. You must also supply the
applicable TNS names or connection strings for a connection, depending on the client
application or tool, type of connection, and service level. You can view or copy the TNS names
and connection strings in the DB Connection dialog for your Autonomous Database. For
detailed information about the TNS names, see Predefined Database Service Names for
Autonomous Transaction Processing and Predefined Database Service Names for Autonomous
Data Warehouse.
You can connect to an Autonomous Database that uses shared Exadata infrastructure from a
VCN with either a public or private endpoint.
To connect to Autonomous Databases that use a public endpoint from a VCN, the VCN must
be configured with one of the following gateways:
Make sure to configure the subnet's route table with a rule that sends the desired traffic to the
specific gateway. Also configure the subnet's security lists to allow the desired traffic.
You can also connect to your database from private IP addresses in your on-premises network
by using transit routing with an Oracle Cloud Infrastructure VCN. This allows traffic to move
directly from your on-premises network to your Autonomous Databasewithout going over the
internet. See Transit Routing: Private Access to Oracle Services for more information on this
method of access.
To connect to Autonomous Databases that use a private endpoint from a VCN, you must
configure a security rule within one of the database's network security groups (NSGs) to allow
access to the Autonomous Database endpoint. For more information on private endpoint
network configuration, see Networking Prerequisites Needed for Private Endpoint.
The client credentials .zip that you download contains the following files:
l tnsnames.ora - SQL*Net configuration file that contains network service names mapped
to connect descriptors for the local naming method
l Java Key Store (JKS) files - Key store files for use with JDBC Thin Connections
Important
For Autonomous Databases on shared Exadata infrastructure, you have the choice of
downloading an instance wallet file or a regional wallet file. The instance wallet contains
only credentials and keys for a single Autonomous Database. The regional wallet contains
credentials and keys for all Autonomous Databases in a specified region. For security
purposes, Oracle recommends that regional wallets be used only by database administrators,
and that instance wallets be supplied to other users whenever possible.
For Autonomous Databases on dedicated Exadata infrastructure, the wallet file contains only
credentials and keys for a single Autonomous Database.
For Autonomous Databases on shared Exadata infrastructure, you can rotate an instance or
regional wallet for security purposes. When your wallet rotation is complete, you will have a
new set of certificate keys and credentials, and the old wallet's keys and credentials will be
invalid. Rotating an instance wallet does not invalidate the regional wallet that covers the
same database instance. Rotating a regional wallet affects all databases in the specified
region. User session termination begins after wallet rotation completes, however this process
does not happen immediately.
Important
The Autonomous Database is preconfigured to support Oracle Net Services (a TNS listener is
installed and configured to use secure TCPS and client credentials.) The client computer must
be prepared to use Oracle Net Services to connect to the Autonomous Database. Preparing
your client includes downloading the client credentials. See the following links for steps you
might have to perform before you access the client credentials and connection information for
your Autonomous Database
3. In the list of Autonomous Databases, click on the display name of the database you are
interested in.
4. Click DB Connection.
5. Select the DB Connection option.
6. Click the DB Connection tab.
7. To obtain the client credentials, click Download.
You will be prompted to provide a password to encrypt the keys inside the wallet. The
password must be at least 8 characters long and must include at least 1 letter and either
1 numeric character or 1 special character.
Save the client credentials zip file to a secure location. See About Downloading Client
Credentials for information about the files included in the download.
8. Take note of or copy the TNS names or connection strings you need for your connection.
See About Connecting to Autonomous Databases for information about making
connections.
WHAT NEXT?
6. Click Rotate Wallet. A confirmation dialog will prompt you to enter the database name
to confirm the rotation.
7. Enter the name of the database, then click Rotate Wallet.
The rotation takes a few minutes to complete.
To obtain access URLs for Oracle Application Express (APEX) and Oracle SQL
Developer Web for an Autonomous Database on dedicated Exadata
infrastructure
1. Open the navigation menu. Under Database, click Autonomous Transaction
Processing or Autonomous Data Warehouse.
2. Choose your Compartment.
3. In the list of Autonomous Databases, click on the display name of the database you are
interested in.
4. Select the Application Connection option.
5. Application URLs are displayed in plain text in the Application URL field. Copy the URL
string using the Copy link.
6. Paste the URL into a browser running on a Compute instance that is inside of the VCN of
the Autonomous Database. Alternately, you can use the URL with a compute instance
that has a direct connection to the VCN of the Autonomous Database.
Use the UpdateAutonomousDatabaseWalletDetails API operation to rotate the wallet for your
Autonomous Database.
Use the AutonomousDatabase API operation to get the access URLs for Application Express
(APEX) and SQL Developer Web.
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.
Oracle Cloud Infrastructure automatically backs up your Autonomous Databases and retains
these backups for 60 days. Automatic backups are weekly full backups and daily incremental
backups. You can also create manual backups to supplement your automatic backups. Manual
backups are stored in an Object Storage bucket that you create, and are retained for 60 days.
Note
Prerequisites
l To create or manage Autonomous Database backups, 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. See Authentication and Authorization for more information on user
authorizations for the Oracle Cloud Infrastructure Database service. See Let database
and fleet administrators manage Autonomous Databases for sample Autonomous
Database policies. See Details for the Database Service for detailed information on
policy syntax.
l To create a manual backup for an Autonomous Database, you must first configure an
Object Storage bucket to serve as a destination for your manual backups. See Setting
Up a Bucket to Store Manual Backups for instructions.
Tip
6. In the Create Manual Backup dialog, enter a name for your backup. Avoid entering
confidential information.
7. Click Create. Your backup may take several hours to complete, depending on the size
of your database.
8. Optionally, you can check the state of your backup in the list of backups on the database
details page. For some states, an information icon ( ) is displayed to provide
additional details regarding the state or ongoing operations like deletions. The backup
has one of the following states:
l Creating
l Active
l Deleting
l Deleted
l Failed
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.
l ListAutonomousDatabaseBackups
l GetAutonomousDatabaseBackup
l CreateAutonomousDatabaseBackup
You must create an Oracle Cloud Infrastructure Object Storage bucket to hold your
Autonomous Database manual backups and configure your database to connect to it. This is a
one-time operation.
To set up an object store and user credentials for your manual backups
Some of the steps in this procedure require you to connect to the database by using an Oracle
Database client such as SQL Developer. See Connecting with Oracle SQL Developer (18.2 or
later) for information and instructions on connecting to an Autonomous Transaction Processing
database. See Connecting with Oracle SQL Developer (18.2 or later) for information and
instructions on connecting to an Autonomous Data Warehouse database.
1. If you have not already done so, generate an auth token for the Oracle Cloud
Infrastructure Object Storage user to access the bucket you create in the next step. See
To create an auth token to learn how to do this. (You will need this auth token for the
database credential you create in step 4.)
2. In the Oracle Cloud Infrastructure Console, create a bucket in your designated Object
Storage Swift compartment to hold the backups. The format of the bucket name is
backup_databasename, where databasename is lowercase.
For example, if you provision a database named DATABASE1, the bucket name should
be backup_database1.
Note
3. Using an Oracle Database client, log in to the database as the administrator set the
database default_bucket property to your Oracle Cloud Infrastructure Object Storage
tenancy URL. The format of the tenancy URL is
https://swiftobjectstorage.region.oraclecloud.com/v1/object_storage_namespace.
For example:
ALTER DATABASE PROPERTY SET default_bucket='https://swiftobjectstorage.us-phoenix-
1.oraclecloud.com/v1/ansh8lvru1zp';
Tip
4. With the tenancy user and the auth token referenced in step 1, create the credential for
your Oracle Cloud Infrastructure Object Storage account. Use DBMS_CLOUD.CREATE_
CREDENTIAL to create the credential.
For example:
BEGIN
DBMS_CLOUD.CREATE_CREDENTIAL(
credential_name => 'DEF_CRED_NAME',
username => '[email protected]',
password => '<auth_token>'
);
END;
/
To list the current value for the default bucket, run the following command:
SELECT PROPERTY_VALUE from database_properties WHERE PROPERTY_NAME='DEFAULT_BUCKET';
After completing these steps you can take manual backups any time you want.
You can use any existing manual or automatic backup to restore your database, or you can
restore and recover your database to any point in time in the 60-day retention period of your
automatic backups. For point-in-time restores, you specify a timestamp, and your
Autonomous Database decides which backup to use for the fastest restore.
Note
Prerequisites
To restore Autonomous Databases, 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. See Authentication and
Authorization for more information on user authorizations for the Oracle Cloud Infrastructure
Database service. See Let database and fleet administrators manage Autonomous Databases
for sample Autonomous Database policies. See Details for the Database Service for detailed
information on policy syntax.
8. Click Restore.
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.
Note
Clone Types
The clone feature offers the following two types of Autonomous Database clones:
l The full-clone option creates a database that includes the metadata and data from the
source database.
l The metadata-clone option creates a database that includes only the metadata from the
source database.
Clone Sources
You can use a running database to create a clone. For databases running on shared Exadata
infrastructure, you can also use a backup as the source of your clone. When using a backup,
you can select a listed backup to clone from, or create a point-in-time clone. Point-in-time
clones contain all data up to a specified timestamp. The specified timestamp must be in the
past.
Note
Prerequisites
To clone an Autonomous Database, you must have 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 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. See Authentication and Authorization for more
information on user authorizations for the Oracle Cloud InfrastructureDatabase service.
When cloning a database on dedicated Exadata infrastructure, the password you set for the
target database cannot be one of the three most recently used passwords of the source
database.
CLONE TYPE
Select the type of clone you want to create. Choose either Full Clone or Metadata
Clone.
CLONE SOURCE
The clone source selection allows you to specify whether the clone is created from a
running database or from a database backup. Select one of the following options:
l Clone from running database: Creates a clone of a running database as it
exists at the current moment.
l Clone from a backup: Creates a clone from a database backup. If you choose
this option, select one of the following options:
o Specify a timestamp: Creates a point-in-time clone.
o Select from a list of backups: Creates a clone using all data from the
specified backup. To limit your list of backups to a specific date range, enter
the starting date in the From field and the ending date in the To field.
Note: You must select a backup that is at least 2 hours old, or the clone
operation will fail.
DATABASE INFORMATION
Note
l Storage: Specify the storage you wish to make available to your Autonomous
Database database, in terabytes. You can make up to 128 TB available. For full
clones, the size of the source database determines the minimum amount of
storage you can make available.
l Enable Preview Version: (This option only displays during periods when a
preview version of Autonomous Database is available) Select this option to
provision the database with an Autonomous Database preview version. Preview
versions of Autonomous Database are made available for limited periods for
testing purposes. Do not select this option if you are provisioning a database for
production purposes or if you will need the database to persist beyond the limited
availability period of the preview version.
ADMINISTRATOR CREDENTIAL
Set the password for the Autonomous Database Admin user by entering a password that
meets the following criteria. You use this password when accessing the Autonomous
LICENSE TYPE
The type of license you want to use for the Autonomous Transaction Processing
database. Your choice affects metering for billing. You have the following options:
l My Organization Already Owns Oracle Database Software Licenses: This
choice is used for the Bring Your Own License (BYOL) license type. If you choose
this option, make sure you have proper entitlements to use for new service
instances that you create.
l Subscribe to New Database Software Licenses and the Database Cloud
Service: This is used for the License Included license type. With this choice, the
cost of the cloud service includes a license for the Database service.
5. Click Create Autonomous Database Clone.
The Console displays the details page for the new clone of your database and the service
begins provisioning the Autonomous Database. Note the following:
l The new clone displays the Provisioning lifecycle state until the provisioning process
completes.
l The source database remains in the Available lifecycle state.
l Backups associated with the source database are not cloned for either the full clone or
the metadata clone option.
l Oracle recommends that you evaluate the security requirements for the new database
and implement them, as applicable. See Security Considerations for details.
WHAT NEXT?
The Console displays the details page for the new clone of your database and the service
begins provisioning the Autonomous Database. Note the following:
l The new clone displays the Provisioning lifecycle state until the provisioning process
completes.
l The source database remains in the Available lifecycle state.
l Backups associated with the source database are not cloned for either the full-clone or
the metadata-clone option.
l Oracle recommends that you evaluate the security requirements for the new database
and implement them, as applicable. See Network Security Groups for Databases
Resources That Use Private Endpoints for details.
WHAT NEXT?
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.
For information about optimizer statistics, resource management rules and performance data
for a cloned database, see the Using Oracle Autonomous Data Warehouse and Using Oracle
Autonomous Transaction Processing user guides.
Maintenance Duration
For Autonomous Databases with shared Exadata infrastructure, Oracle performs regular
maintenance updates that generally take no more than two hours.
To see when your next scheduled maintenance update is, navigate to the Autonomous
Database details page in the Console for the database you are interested in. The Next
Maintenance metadata field displays the beginning and ending times of the next database
maintenance . You can also use the GetAutonomousDatabase API operation to determine the
time of your next maintenance update.
Each level of the architecture model corresponds to one of the following resources types:
o Allows for easier testing, as development databases can be housed within the
same container as production databases
o Allows for the separation of duties between database administrators, who manage
only the individual Autonomous Database instances to which they are granted
privileges, and fleet managers, who manage infrastructure resources and
container databases.
l An Autonomous Database. You can create multiple Autonomous Databases within
the same container database. This level of the database architecture is analogous to the
pluggable databases (PDBs) found in non-Autonomous Exadata systems. Your
Autonomous Database can be configured for either transaction processing or data
warehouse workloads.
You must create the dedicated Exadata infrastructure resources in the following order:
l A Virtual Cloud Network (VCN) and a Subnet, which you create using Oracle Cloud
Infrastructure's Networking service. You must have at least one VCN and one subnet
available to provision an Autonomous Database with dedicated Exadata infrastructure.
For more information, see the following topics:
o Network Isolation (from Fleet Administrator’s Guide to Oracle Autonomous
Transaction Processing on Dedicated Exadata Infrastructure)
o Overview of Networking
o To create a VCN
o To create a subnet
l Autonomous Backups, created for you automatically by the Autonomous Database
service. By default, backups are stored for 60 days. Using the Console, you can choose
to change the retention period to 7, 15, or 30 days.
l Manual Backups. Optionally, you can create on-demand manual backups. Manual
backups are subject to the retention policy you have in place for the Autonomous
Container Database.
User Roles
Your organization may choose to split the administration of the Autonomous Database on
dedicated Exadata infrastructure into the following roles:
l Database User. Database users are the developers who write applications that
connect to and use an Autonomous Database to store and access the data. Database
users do not need Oracle Cloud Infrastructure accounts. They gain network connectivity
to and connection authorization information for the database from the database
administrator.
Additionally, you can scale the CPU count and the storage capacity of the database at any time
without impacting availability or performance.
Tip
Infrastructure maintenance takes place at least once each quarter and is mandatory. You can
schedule a maintenance window to control the time, day of the week, and week of the month
that your infrastructure maintenance will begin. Infrastructure maintenance runs are for
infrastructure patching (including patching of the Exadata grid infrastructure code and
operating systems updates), and do not include database patching. Oracle will notify you in
the weeks leading up to the quarterly infrastructure patching date about the upcoming
maintenance. You can also view scheduled maintenance runs in the Oracle Cloud
Infrastructure console. The following tasks explain how to view scheduled and past
maintenance updates, and how to edit the maintenance schedule for an infrastructure
instance:
Container database maintenance updates include Oracle Database software patches and take
place at least once each quarter. You can configure a maintenance window to control the time,
day of the week, and week of the month that your maintenance update run will begin.
Otherwise, Oracle will schedule container database maintenance runs for you so that they are
coordinated with the maintenance runs of the associated Exadata infrastructure.
Tip
If a scheduled container database maintenance run cannot take place (because of changes
made to infrastructure maintenance scheduling or other reasons), Oracle will automatically
reschedule the container database maintenance for the following quarter. You can change
your container database maintenance window or reschedule a single container database
maintenance run to ensure that your container database maintenance runs follow
infrastructure maintenance within the same quarter.
l Release Update (RU): Autonomous Database installs only the most current release
update.
l Release Update Revision (RUR): Autonomous Database installs the release update plus
additional fixes.
The following tasks explain how to view and edit maintenance updates information for
Autonomous Container Databases:
Autonomous Database emits events for Autonomous Exadata Infrastructure and Autonomous
Container Database maintenance runs. Using the Notifications service (which consumes
events), you can create and subscribe to a Notifications topic, allowing you to receive
notifications about your maintenance runs by email, PagerDuty alert, Slack, or https.
See Getting Started with Events to learn about creating and subscribing to an Events topic.
See Services that Produce Events for a full list of Database service events. See Managing
Topics and Subscriptions to learn how to create and subscribe to a Notifications topic.
Oracle Cloud Infrastructure currently offers Autonomous Database with the following
dedicated Exadata infrastructure system models and configurations:
The subsections that follow provide the details for each shape's configuration.
EXADATA X8 S HAPES
Number of Exadata 3 6 12
Storage Servers
EXADATA X7 S HAPES
Note
Additional Information
For known issues, see Known Issues for Oracle Autonomous Database on Dedicated Exadata
Infrastructure.
Note
Private endpoint refers to a network setup for your Autonomous Database with shared
Exadata infrastructure where all network traffic moves through a private endpoint within a
VCN in your tenancy. If your organization has strict security mandates that do not allow you to
have a public endpoint for your database, this provides you with the necessary private
endpoint. Additionally, this configuration uses no public subnets and allows you to keep all
traffic to and from your Autonomous Database off of the public internet.
Enabling a private endpoint for an Autonomous Database ensures that the only access path to
the database is via a VCN inside your Oracle Cloud Infrastructure tenancy. This network
configuration completely blocks access to the database from public endpoints. A private
endpoint offers the following advantages over other methods of private network access:
l Does not require you to set up transit routing in you VCN and use a service gateway to
connect.
l Can satisfy security requirements that forbid the use of a public endpoint.
The private endpoint option is available for both new and existing Autonomous Databases on
shared Exadata infrastructure. See To create an Autonomous Database on shared Exadata
infrastructure for instructions on creating a new Autonomous Database with a private
endpoint. See To change the network access type of an Autonomous Database on shared
Exadata infrastructure from public endpoint to private endpoint for information on switching
network access configuration of an existing database. Note that your Oracle Database version
must be 19c or higher to perform an in-place switch the network access type after
provisioning.
To provision an Autonomous Database with a private endpoint, you must have the following
resources already created:
l A VCN within the region that will contain your Autonomous Database with shared
Exadata infrastructure. Cannot be changed after provisioning.
l A private subnet within your VCN configured with default DHCP options. Cannot be
changed after provisioning.
l At least 1 network security group (NSG) within your VCN for the Autonomous Database.
Can be changed or edited after provisioning.
NSGs create a virtual firewall for your Autonomous Database using security rules. You can
specify up to five NSGs to control access to your Autonomous Database.
l The private endpoint feature supports both stateful and stateless security rules within
NSGs.
l Your rule covering ingress traffic must specify the IP Protocol "TCP", and your
Destination Port Range must be 1522.
To connect another resource located inside Oracle Cloud Infrastructure (for example, a
Compute instance) to your Autonomous Database, the second resource needs a security rule
that allows all egress traffic to the NSG of the Autonomous Database. This means you specify
the NSG of the Autonomous Database as the Destination for this security rule. The second
resource's security rule can be part of an NSG or a security list.
See Network Security Groups and To create an NSG for more information on working with
NSGs.
You can connect to an Autonomous Database that uses a private endpoint from within Oracle
Cloud Infrastructure resources, or from your data center. See To find the Fully Qualified
Domain Name (FQDN) and IP address of your private endpoint for information on locating the
IP address and URL of your endpoint.
You can connect from a resource (like a Compute instance) within the same VCN as the
private endpoint. Note that you can also connect from a resource located in a different VCN
from the private endpoint by using local or remote VCN peering.
Example network layout for connecting to an Autonomous Database with a private endpoint
from within Oracle Cloud Infrastructure
Example stateful security rule for the Autonomous Database NSG. Note that stateless
rules are also supported.
l An NSG security rule for the resource that will be allowed access to the Autonomous
Database. This stateful egress security rule allows all egress traffic to the NSG of the
Autonomous Database.
Example stateful egress security rule for the NSG of the resource connecting to the
Autonomous Database
Example network layout for connecting to an Autonomous Database with a private endpoint
from an on-premises network
Tip
To find the Fully Qualified Domain Name (FQDN) and IP address of your
private endpoint
Your database's private endpoint IP address is displayed on the Autonomous Database
Details page in the Oracle Cloud Infrastructure Console.
4. On the Autonomous Database Details page, in the Network section, the Private
Endpoint IP Private Endpoint URL fields display the IP address and URL of the
endpoint.
Alternatively you can set up a hybrid DNS in Oracle Cloud Infrastructure for DNS name
resolution.
Additional Information
See Private Access in the Networking service documentation for an overview of the options
for enabling private access to services within Oracle Cloud Infrastructure.
See Hanging Connection in the Networking service documentation for troubleshooting IPSec
VPN connection issues that can occur when connecting from your on-premises network.
The infrastructure resource includes the physical Exadata hardware and intelligent Exadata
software. Once you have provisioned an infrastructure instance, you can provision one or
more Autonomous Container Databases to run on your infrastructure. To provision an
Autonomous Database, you must have both an infrastructure resource and at least one
container database available.
Note
Prerequisites
Tip
l You will also need a Virtual Cloud Network and a Subnet, which you create using
Oracle Cloud Infrastructure's Networking service. For information on creating and
managing these resources, see VCNs and Subnets.
Note that if you choose a subnet with a security list, the security rules for the
infrastructure resource will be a union of the rules in the security list and the
NSGs.
7. Optionally, you can specify the date and start time for the Autonomous Exadata
Infrastructure quarterly maintenance.
Tip
e. For Day of the Week, select the day of the week that the maintenance will take
place.
f. For Start Hour, select one of the six start time windows available. The
maintenance will begin during the 4 hour time window that you specify and may
continue beyond the end of the period chosen. The start time window is specified
in universal coordinated time (UTC).
g. Click Update Maintenance Schedule.
8. Choose the license type you wish to use. Your choice affects metering for billing. You
have the following options:
l Bring your own license: If you choose this option, make sure you have proper
entitlements to use for new service instances that you create.
l License included: With this choice, the cost of the cloud service includes a
license for the Database service.
9. The following Advanced Options are available:
Tags - Optionally, you can apply 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. Avoid entering confidential
information.
10. Click Create Autonomous Exadata Infrastructure.
WHAT NEXT?
After creating an Autonomous Exadata Infrastructure resource, you can create one or more
Autonomous Container Databases on your infrastructure. You must have provisioned both an
infrastructure resource and at least one container database before you can create your first
Autonomous Database in Oracle Cloud Infrastructure.
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.
Note
Tip
9. Under Day of the week, specify the day of the week on which the maintenance will
occur.
10. Under Start hour, specify the hour during which the maintenance run will begin.
11. Click Update Maintenance Schedule.
5. On the Autonomous Exadata Infrastructure details page, under Maintenance, click the
view link in the Next Maintenance field.
6. On the Maintenance page, under Autonomous Database Maintenance, click
History. In the list of past maintenance events, you can click on an individual event
title to read the details of the maintenance that took place. Maintenance event details
include the following:
l The category of maintenance (quarterly software maintenance, hardware
maintenance, or a critical patch)
l Whether the maintenance was scheduled or unplanned
l The OCID of the maintenance event. (Go to More Actions, then choose Copy
OCID.)
l The start time and date of the maintenance
infrastructure instance will be a union of the rules in the security list and the NSGs. For more
information, see Network Security Groups.
Note
Warning
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.
Use the GetMaintenanceRun API to view the details of a maintenance run that is scheduled, in
progress, or that has ended.
Use the ListMaintenanceRun API to get a list of maintenance runs in a specified compartment.
Note
Prerequisites
l To create an Autonomous Container Database, 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. See Authentication and Authorization for more information on user
authorizations for the Oracle Cloud Infrastructure Database service.
Tip
WHAT NEXT?
After creating an Autonomous Container Database, you can create one or more Autonomous
Databases within the container database.
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.
Note
l Edit the backup retention policy. By default, database backups are retained for 60 days.
You have the option of retaining backups for 7, 15, 30, or 60 days. The current backup
retention policy for an Autonomous Container Database is displayed on the Autonomous
Container Database details page.
l Configure the type of database maintenance. You can choose to use Release Update
(RU) or Release Update Revision (RUR) updates for your Autonomous Container
Database maintenance. Release Update (RU): Autonomous Database installs only the
most current release update. Release Update Revision (RUR): Autonomous Database
installs the release update plus additional fixes.
For information about Release Updates (RUs) and Release Updatate Revisions (RURs),
see Release Update Introduction and FAQ (Doc ID 2285040.1) in the My Oracle Support
online help portal (MOS login required).
l Configure the scheduling for your Autonomous Container Database.
l View the Autonomous Container Database next scheduled maintenance and
maintenance history.
l Skip a scheduled maintenance run. For container databases, you can skip maintenance
runs for up to 2 consecutive quarters if needed.
l Perform a rolling restart of databases within an Autonomous Container Database. You
can perform a "rolling restart" on all the Autonomous Databases in an Autonomous
Container Database to ensure that the current memory allocation is optimized. During a
rolling restart, each node of an Autonomous Database is restarted separately while the
remaining nodes continue to be available. No interruption of service occurs during a
5. On the Autonomous Container Database details page, under Maintenance, click the
edit link in the Maintenance Details field. In the Edit Automatic Maintenance
dialog that opens, you can configure both the maintenance schedule and the patch type.
6. Optionally, you can change the maintenance patch type. To edit this setting, select
either Release Update (RU) or Release Update Revision (RUR). Learn more.
7. To configure the maintenance schedule, select Specify a schedule in the Configure
the automatic maintenance schedule section. Choose your preferred month, week,
weekday, and start time for container database maintenance. Autonomous Container
Database maintenance should be scheduled so that it follows after the maintenance
scheduled for the associated Autonomous Exadata Infrastructure. To see the scheduling
of the associated Autonomous Exadata Infrastructure, you can click Show
Autonomous Exadata Infrastructure maintenance schedule. If you have not
specified an infrastructure maintenance schedule (and Oracle is scheduling
infrastructure maintenance), your infrastructure maintenance scheduling will be
automatically modified so that it precedes your container database maintenance during
each quarter.
l Under Maintenance months, specify at least one month for each quarter during
which Autonomous Exadata Infrastructure maintenance will take place.
l Under Week of the month, specify which week of the month maintenance will
take place. Weeks start on the 1st, 8th, 15th, and 22nd days of the month, and
have a duration of 7 days. Weeks start and end based on calendar dates, not days
of the week. Maintenance cannot be scheduled for the fifth week of months that
contain more than 28 days.
l Under Day of the week, specify the day of the week on which the maintenance
will occur.
l Under Start hour, specify the hour during which the maintenance run will begin.
8. Click Save Changes.
4. In the list of Autonomous Container Databases, click on the display name of the
container database you are interested in.
5. On the Autonomous Container Database details page, under Maintenance, click the
View link in the Next Maintenance field.
6. On the Maintenance page, under Autonomous Database Maintenance, click
Maintenance. In the list of maintenance events, you can the details of scheduled
maintenance runs. Maintenance event details include the following:
l The status of the scheduled maintenance run
l The type of maintenance run (quarterly software maintenance or a critical patch)
l The OCID of the maintenance event.
l The start time and date of the maintenance
4. In the list of Autonomous Container Databases, click on the display name of the
container database you are interested in.
5. On the Autonomous Container Database details page, click Restart.
6. In the confirmation dialog, type the name of the Autonomous Container Database.
7. Click Restart.
Note
Warning
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.
Use the ListMaintenanceRun API to get a list of maintenance runs in a specified compartment.
Can be used to see maintenance history and scheduled maintenance runs.
Note
Tip
SQL Developer Web is a browser-based interface of Oracle SQL Developer and provides a
subset of the features of the desktop version.
For more information, see the Autonomous Transaction Processing and Autonomous Data
Warehouse user guides. Each guide contain a section on using SQL Developer Web with
Autonomous Databases. Use the following links:
Complete product information can be found in About Oracle SQL Developer Web.
Oracle Application Express (APEX) is a low-code development platform that enables you to
build scalable, secure enterprise applications with world-class features that can be deployed
anywhere. APEX provides you with an easy-to-use browser-based environment to load data,
manage database objects, develop REST interfaces, and rapidly build applications for both
desktop and mobile devices.
Oracle Application Express is available for databases with both the dedicated Exadata
infrastructure and shared Exadata infrastructuredeployment options.
For complete information, see the APEX topics in the Autonomous Transaction Processing and
the Autonomous Data Warehouse user guides. Use the following links:
Machine Learning is currently available for databases with shared Exadata infrastructure only.
WHAT NEXT?
The Console provides access URLs for Application Express (APEX) and SQL Developer Web
that you can use to connect to these applications. The URLs only work from browsers within
the same VCN as the Autonomous Database being accessed by the applications. Therefore, to
use these URLs, you will need to open a browser running on a computer that meets one of the
following conditions:
To access APEX or SQL Developer Web, paste the appropriate access URL into the browser's
address field, and then provide the Autonomous Database username and password when
prompted. For more information on APEX, see the APEX documentation. For more information
on SQL Developer Web, see Oracle SQL Developer Web.
The following tasks explain how to obtain an access URLs for APEX and SQL Developer Web.
To obtain the access URL for Oracle SQL Developer Web for an Autonomous
Database on dedicated Exadata infrastructure
1.
Open the navigation menu. Under Database, click Autonomous Transaction
Processing or Autonomous Data Warehouse.
2. Choose your Compartment.
3. In the list of Autonomous Databases, click on the display name of the database you
want to work with.
4. Click the Tools tab on the Autonomous Database Details page.
5. Click Open SQL Developer Web
To obtain the access URLs for Oracle Application Express (APEX) for an
Autonomous Database on dedicated Exadata infrastructure
1.
Open the navigation menu. Under Database, click Autonomous Transaction
Processing or Autonomous Data Warehouse.
2. Choose your Compartment.
3. In the list of Autonomous Databases, click on the display name of the database you
want to work with.
4. Click the Tools tab on the Autonomous Database Details page.
5. Click Open APEX
Always Free Autonomous Databases support only a single Oracle Database version.
l You can see only the installed Always Free database version on the details page.
l If your Always Free database is not the latest version, Oracle automatically migrates it
to the latest version.
Note
Tip
After provisioning, you can continue using your Always Free Autonomous Database for as long
as you want at no charge. You can terminate the database at any time.
If your Always Free Autonomous Database has no activity for a period of 7 consecutive days,
the Database service will stop the database automatically. If this happens, restart the
database and continue using it. If your Always Free Autonomous Database remains in a
stopped state for 3 consecutive months, the database will be reclaimed (automatically
terminated) by the Database service.
USING EVENTS AND NOTIFICATIONS TO S TAY I NFORMED ABOUT I NACTIVE ALWAYS FREE AUTONOMOUS
DATABASES
You can use Oracle Cloud Infrastructure's Events service to send structured JSON messages
about your Always Free Autonomous Database lifecycle events to applications used for
automation. For example, you can create automatic email, Slack, PagerDuty, or HTTPS
notifications (using the Notifications service) to be alerted if a database is going to be stopped
or terminated in the next 48 hours. You can also set up notifications to be alerted when a
database is automatically stopped or and terminated.
l Getting Started with Events for details on working with Events messages.
l Autonomous Database Event Types for details on the currently available Always Free
Autonomous Database lifecycle events messages.
l How Notifications Works for an overview of setting up automated notifications based on
the JSON messages emitted by the Events service.
Exadata DB Systems
Exadata DB systems allow you to leverage the power of Exadata within the Oracle Cloud
Infrastructure. An Exadata DB system consists of a base system, quarter rack, half rack, or
full rack of compute nodes and storage servers, tied together by a high-speed, low-latency
InfiniBand network and intelligent Exadata software. You can configure automatic backups,
optimize for different workloads, and scale up the system to meet increased demands.
Note
Note
Subscription Types
The only subscription type available for Exadata DB systems is the Monthly Flex purchase
model under Universal Credit Pricing. See https://www.oracle.com/cloud/bring-your-own-
license/faq/universal-credit-pricing.html for more information.
l Scaling within an Exadata DB system lets you modify compute node processing power
within the system.
l Scaling across Exadata DB system configurations lets you move to a different
configuration, for example, from a quarter rack to a half rack.
If an Exadata DB system requires more compute node processing power, you can scale up the
number of enabled CPU cores symmetrically across all the nodes in the system. For a base
system or a quarter rack, you can scale in multiples of 2 across the 2 database compute
nodes. For a half rack, you can scale in multiples of 4 across the 4 database compute nodes.
For a full rack, you can scale in multiples of 8 across the 8 database compute nodes.
For a non-metered Exadata DB system, you can temporarily modify the compute node
processing power (bursting) or add compute node processing power on a more permanent
basis. For a metered Exadata DB system, you can simply modify the number of enabled CPU
cores.
You can provision an X8 or X7 Exadata DB system, or an Exadata base system, with zero CPU
cores, or scale the DB system down to zero cores after you provision it. With zero cores, you
are billed only for the infrastructure until you scale up the system. For detailed information
about pricing, see https://www.oracle.com/database/exadata-cloud-service-pricing.html.
Tip
For information on CPU cores per configuration, see System Configuration. To learn how to
scale a system, see To scale an Exadata DB system.
Scaling across Exadata DB system configurations enables you to move to a different system
configuration. This is useful when a database deployment requires:
l Processing power that is beyond the capacity of the current system configuration.
l Storage capacity that is beyond the capacity of the current system configuration.
l A performance boost that can be delivered by increasing the number of available
compute nodes.
To assist with moving your database deployments between Exadata DB systems, you can
restore a backup to a different Exadata DB system that uses a larger shape, or create a Data
Guard associations for your database and then perform a switchover so that your new standby
database assumes the primary role. To start the process, contact Oracle and request a service
limit increase so that you can provision the larger Exadata Cloud Service instance needed by
your database.
System Configuration
Exadata DB systems are offered in base system, quarter rack, half rack, or full rack
configurations, and each configuration consists of compute nodes and storage servers. The
compute nodes are each configured with a Virtual Machine (VM). You have root privilege for
the compute node VMs, so you can load and run additional software on them. However, you do
not have administrative access to the Exadata infrastructure components, including the
physical compute node hardware, network switches, power distribution units (PDUs),
integrated lights-out management (ILOM) interfaces, or the Exadata Storage Servers, which
are all administered by Oracle.
You have full administrative privileges for your databases, and you can connect to your
databases by using Oracle Net Services from outside the Oracle Cloud Infrastructure. You are
responsible for database administration tasks such as creating tablespaces and managing
database users. You can also customize the default automated maintenance set up, and you
control the recovery process in the event of a database failure.
The subsections that follow provide the details for each shape's configuration.
Exadata X8 Shapes
Number of Exadata 3 6 12
Storage Servers
Exadata X8 shapes provide 700 GB of user disk space for database homes.
Exadata X7 Shapes
Number of Compute 2 4 8
Nodes
Total Minimum 0 0 0
Number of Enabled
CPU Cores
Number of Exadata 3 6 12
Storage Servers
Exadata X6 Shapes
Exadata X6 shapes provide 200 GB of user disk space for database homes.
The system configuration of an Exadata base system is similar to a quarter rack with some
differences in capacity.
Property Value
Property Value
Storage Configuration
When you launch an Exadata DB system, the storage space inside the Exadata storage servers
is configured for use by Oracle Automatic Storage Management (ASM). By default, the
following ASM disk groups are created:
l The DATA disk group is intended for the storage of Oracle Database data files.
l The RECO disk group is primarily used for storing the Fast Recovery Area (FRA), which
is an area of storage where Oracle Database can create and manage various files
related to backup and recovery, such as RMAN backups and archived redo log files.
l The /acfs file systems contain system files that support various operations. You should
not store custom files, Oracle Database data files, or backups inside the ACFS disk
groups. Custom ACFS mounts can be created using the DATA ASM disk group for files
that are not service-related.
The disk group names contain a short identifier string that is associated with your Exadata
Database machine environment. For example, the identifier could be C2, in which case the
DATA disk group would be named DATAC2, the RECO disk group would be named RECOC2, and
so on.
In addition, you can create a SPARSE disk group. A SPARSE disk group is required to support
Exadata snapshots. Exadata snapshots enable space-efficient clones of Oracle databases that
can be created and destroyed very quickly and easily. Snapshot clones are often used for
development, testing, or other purposes that require a transient database.
Note that you cannot change the disk group layout after service creation.
If you choose to perform database backups to the Exadata storage, or to create a sparse disk
group, or to do both, your choices profoundly affect how storage space in the Exadata storage
servers is allocated to the ASM and sparse disk groups.
The table that follows shows the approximate percentages of storage allocated for DATA,
RECO, and SPARSE disk groups for each possible configuration.
automation and lifecycle operations, enabling Oracle Cloud Infrastructure to be the best cloud
solution for enterprise databases and applications.
periodically inspects and repairs hard disks during idle time. If bad sectors are
detected on a hard disk, then Oracle Exadata Storage Server automatically sends
a request to Oracle Automatic Storage Management to repair the bad sectors by
reading the data from another mirror copy. Finally, Exadata and Oracle Automatic
Storage Management can detect corruptions as data blocks are read into the
buffer cache and automatically repair data corruption with a good copy of the data
block on a subsequent database write. This inherent intelligent data protection
makes Exadata and Exadata Cloud the best data protection storage platform for
Oracle Databases. For comprehensive data protection, a Maximum Availability
Architecture best practice is to use a standby database on a separate Exadata to
detect, prevent, and automatically repair corruptions that cannot be addressed by
Exadata, alone. The standby database also minimizes downtime and data loss for
disasters that result from site, cluster, and database failures.
o Response time quality of service: Only Exadata has end-to-end quality-of-
service capabilities to ensure that response time remains low and optimum.
Database server I/O capping and Exadata storage I/O latency capping ensures
that read or write I/O can be redirected to partnered cells when response time
exceeds a certain threshold. If storage becomes unreliable (but not failed)
because of poor and unpredictable performance, then the disk or flash cache can
be quarantined, offline, and later brought back online if heuristics show that I/O
performance is back to acceptable levels. Resource management can help
prioritize key database network or I/O functionality, so that your application and
database perform at an optimized level. For example, database log writes get
priority over backup requests on the Exadata network and storage. Furthermore,
rapid response time is maintained during storage software updates by ensuring
that partner flash cache is warmed so flash misses are minimized.
o End-to-end testing and holistic health checks: Because Oracle owns the
entire Exadata Cloud infrastructure, end-to-end testing and optimizations benefit
every Exadata customer around the world, whether hosted on premise or in the
cloud. Validated optimizations and fixes required to run any mission-critical
system are uniformly applied after rigorous testing. Health checks are designed
to evaluate the entire stack. The Exadata health check utility EXACHK is Exadata
cloud-aware and highlights any configuration and software alerts that may have
occurred because of customer changes. No other cloud platform currently has this
kind of end-to-end health check available. For Oracle Autonomous Database,
EXACHK runs automatically to evaluate Maximum Availability Architecture
compliance. For non-autonomous databases, Oracle recommends running EXACHK
at least once a month, and before and after any software updates, to evaluate any
new best practices and alerts.
l Cloud Maximum Availability Architecture best practices paper: Maximum
Availability Architecture engineering collaborates with Oracle Cloud teams to integrate
Maximum Availability Architecture practices that are optimized for Oracle Cloud
Infrastructure and security. See MAA Best Practices for the Oracle Cloud for additional
information about continuous availability, Oracle Data Guard, Hybrid Data Guard,
Oracle GoldenGate, and other Maximum Availability Architecture-related topics.
The following table lists various software updates and the impacts associated with those
updates on databases and applications.
Performed by
customer using
cloud-assisted tools
for non-Autonomous
Database
Oracle Minimal downtime with Minimal downtime with Not applicable for
Database DBMS_ROLLING, Oracle DBMS_ROLLING, Oracle Autonomous
upgrade GoldenGate replication, GoldenGate replication, Database
or with pluggable or with pluggable
Performed by
database relocate database relocate
customer using
generic Maximum
Availability
Architecture best
practices
As part of Exadata Cloud, all software updates (except for non-rolling database upgrades) can
be done online or with Oracle RAC rolling updates to achieve continuous database uptime.
Furthermore, any local failures of the storage, Exadata network, or Exadata database server
are managed, automatically, and database uptime is maintained.
To achieve continuous application uptime during Oracle RAC switchover or failover events,
follow these application-configuration best practices:
For more information, see Continuous Availability - Application Continuity for the Oracle
Database.
Exadata Cloud supports all four Maximum Availability Architecture reference architectures,
providing support for all Oracle Databases, regardless of their specific high availability, data
protection, and disaster recovery service-level agreements. See MAA Best Practices for the
Oracle Cloud for more information about Maximum Availability Architecture in the Exadata
Cloud.
l Wherever possible, use the Oracle-supplied cloud interfaces such as the Oracle Cloud
Infrastructure Console, API, or CLI, or cloud-specific tools such as dbaascli and
dbaasapi to perform lifecycle management and administrative operations on your
Exadata DB system. For example, use the exadbcpatchmulti command to apply Oracle
Database patches instead of manually running opatch. In addition, if an operation can
In general, Oracle recommends using regional subnets, which span all availability domains in
the region. If you instead use AD-specific subnets, both the client and backup subnets must be
in the same availability domain. The important thing to know for your DB system is that the
resources you create in the two subnets must be in the same availability domain. For more
information, see About Regional Subnets.
You will create custom route tables for each subnet. You will also create security rules to
control traffic to and from the client network and backup network of the Exadata compute
notes. More information follows about those items.
This option can be useful when doing a proof-of-concept or development work. You can use
this setup in production if you want to use an internet gateway with the VCN, or if you have
services that run only on a public network and need access to the database. See the following
diagram and description.
l Subnets:
o Public client subnet (public means that the resources in the subnet can have public
IP addresses at your discretion).
o Private backup subnet (private means that the resources in the subnet cannot
have public IP addresses and therefore cannot receive incoming connections from
the internet).
l Gateways for the VCN:
o Internet gateway (for use by the client subnet).
o Service gateway (for use by the backup subnet). Also see Option 1: Service
Gateway Access Only to Object Storage.
l Route tables:
o Custom route table for the public client subnet, with a route for 0.0.0.0/0, and
target = the internet gateway.
o Separate custom route table for the private backup subnet, with a route rule for
the service CIDR label called OCI <region> Object Storage, and target = the
service gateway. Also see Option 1: Service Gateway Access Only to Object
Storage.
l Security rules to enable the desired traffic to and from the Exadata nodes. See Security
Rules for the Exadata System.
l Static route on the DB system's compute nodes (to enable access to Object Storage by
way of the backup subnet).
Important
Oracle recommends this option for a production system. Both subnets are private and cannot
be reached from the internet. See the following diagram and description.
l Subnets:
o Private client subnet.
o Private backup subnet.
l Gateways for the VCN:
o Dynamic routing gateway (DRG), with a FastConnect or IPSec VPN to your on-
premises network (for use by the client subnet).
o Service gateway (for use by the backup subnet to reach Object Storage, and for
use by the client subnet to reach the Oracle YUM repo for OS updates). Also see
Option 2: Service Gateway Access to Both Object Storage and YUM Repos.
o NAT gateway (for use by the client subnet to reach public endpoints not supported
by the service gateway).
l Route tables:
o Custom route table for the private client subnet, with two rules:
n A rule for the on-premises network's CIDR, and target = DRG.
n A rule for the service CIDR label called All <region> Services in Oracle
Services Network, and target = the service gateway. The Oracle Services
Network is a conceptual network in Oracle Cloud Infrastructure that is
reserved for Oracle services. The rule enables the client subnet to reach the
regional Oracle YUM repo for OS updates. Also see Option 2: Service
Gateway Access to Both Object Storage and YUM Repos.
n A rule for 0.0.0.0/0, and target = NAT gateway.
o Separate custom route table for the private backup subnet, with one rule:
n The same rule as for the client subnet: for the service CIDR label called All
<region> Services in Oracle Services Network, and target = the
service gateway. This rule enables the backup subnet to reach the regional
Object Storage for backups.
l Security rules to enable the desired traffic to and from the Exadata nodes. See Security
Rules for the Exadata System.
l Static route on the DB system's compute nodes (to enable access to Object Storage by
way of the backup subnet).
If you're setting up Exadata DB systems (and thus VCNs) in more than one region, make sure
the IP address space of the VCNs does not overlap. This is important if you want to set up
disaster recovery with Oracle Data Guard.
The two subnets you create for the Exadata DB system must not overlap with
192.168.128.0/20.
The following table lists the minimum required subnet sizes, depending on the Exadata rack
size. For the client subnet, each node requires two IP addresses, and in addition, three
addresses are reserved for Single Client Access Names (SCANs). For the backup subnet, each
node requires one address.
Tip
The Networking section of the Console includes a handy wizard that creates a VCN along with
related resources. It can be useful if you just want to try launching an instance. However, the
wizard automatically creates a public subnet and an internet gateway. You may not want this
for your production network, so Oracle recommends you create the VCN and other resources
individually yourself instead of using the wizard.
For the nodes to communicate, the VCN must use the Internet and VCN Resolver. It enables
hostname assignment to the nodes, and DNS resolution of those hostnames by resources in
the VCN. It enables round robin resolution of the database's SCANs. It also enables resolution
of important service endpoints required for backing up databases, patching, and updating the
cloud tooling on an Exadata DB system. The Internet and VCN Resolver is the VCN's default
choice for DNS in the VCN. For more information, see DNS in Your Virtual Cloud Network and
also DHCP Options.
When you create the VCN, subnets, and Exadata, you must carefully set the following
identifiers, which are related to DNS in the VCN:
These values make up the node's fully qualified domain name (FQDN):
<hostname_prefix>-######.<subnet_domain_label>.<vcn_domain_
label>.oraclevcn.com
For example:
exacs-abcde1.clientpvtad1.acmevcniad.oraclevcn.com
In this example, you assign exacs as the hostname prefix when you create the Exadata DB
system. The Database service automatically appends a hyphen and a five-letter string with
the node number at the end. For example:
l Node 1: exacs-abcde1.clientpvtad1.acmevcniad.oraclevcn.com
l Node 2: exacs-abcde2.clientpvtad1.acmevcniad.oraclevcn.com
l Node 3: exacs-abcde3.clientpvtad1.acmevcniad.oraclevcn.com
l And so on
l Maximum 12 characters
l Cannot be the string localhost
<12_chars_max>-######.<14_chars_max>.<14_chars_max>.oraclevcn.com
The preceding maximums are not enforced when you create the VCN and subnets. However, if
the labels exceed the maximum, the Exadata deployment fails.
To enable the use of hostnames when on-premises hosts and VCN resources communicate
with each other, you have two options:
To be able to back up databases, and patch and update cloud tools on an Exadata DB system,
you must configure access to Oracle Cloud Infrastructure Object Storage. Regardless of how
you configure the VCN with that access (for example, with a service gateway), you may also
need to configure a static route to Object Storage on each of the compute nodes in the cluster.
This is only required if you are not using automatic backups. If you are using customized
backups using the backup APIs, then you must route traffic destined for Object Storage
through the backup interface (BONDETH1). This is not necessary if you are using the
automatic backups created with the Console, APIs, or CLIs.
Important
As of June 1, 2018, Object Storage no longer supports the following discontinued IP ranges.
Oracle recommends that you remove these older IP addresses from your access-control lists,
firewall rules, and other rules after you have adopted the new IP ranges.
2. Log in as opc and then sudo to the root user. Use sudo su - with a hyphen to invoke the
root user's profile.
login as: opc
10.0.4.1
The file changes from the previous step take effect immediately after the ifdown and
ifup commands run.
6. Repeat the preceding steps on each compute node in the Exadata DB system.
Your VCN needs access to both Object Storage for backups and Oracle YUM repos for OS
updates.
Depending on whether you use option 1 or option 2 described previously, you use the service
gateway in different ways. See the next two sections.
l Perform the tasks for setting up a service gateway on a VCN, and specifically enable the
service CIDR label called OCI <region> Object Storage.
l In the task for updating routing, add a route rule to the backup subnet's custom route
table. For the destination service, use OCI <region> Object Storage and target =
the service gateway.
l In the task for updating security rules in the subnet, perform the task on the backup
network's network security group (NSG) or custom security list. Set up a security rule
with the destination service set to OCI <region> Object Storage. See Rule Required
Specifically for the Backup Network.
Option 2: Service Gateway Access to Both Object Storage and YUM Repos
You configure both the client subnet and backup subnet to use the service gateway for access
to the Oracle Services Network, which includes both Object Storage and the Oracle YUM
repos.
Important
l Perform the tasks for setting up a service gateway on a VCN, and specifically enable the
service CIDR label called All <region> Services in Oracle Services Network.
l In the task for updating routing in each subnet, add a rule to each subnet's custom route
table. For the destination service, use All <region> Services in Oracle Services
Network and target = the service gateway.
l In the task for updating security rules for the subnet, perform the task on the backup
network's network security group (NSG) or custom security list. Set up a security rule
with the destination service set to OCI <region> Object Storage. See Rule Required
Specifically for the Backup Network. Note that the client subnet already has a broad
egress rule that covers access to the YUM repos.
Here are a few additional details about using the service gateway for option 2:
l Both the client subnet and backup subnet use the service gateway, but to access
different services. You cannot enable both the OCI <region> Object Storage service
CIDR label and the All <region> Services in Oracle Services Network for the
service gateway. To cover the needs of both subnets, you must enable All <region>
Services in Oracle Services Network for the service gateway. The VCN can have
only a single service gateway.
l Any route rule that targets a given service gateway must use an enabled service CIDR
label and not a CIDR block as the destination for the rule. That means for option 2, the
route tables for both subnets must use All <region> Services in Oracle Services
Network for their service gateway rules.
l Unlike route rules, security rules can use either any service CIDR label (whether the
VCN has a service gateway or not) or a CIDR block as the source or destination CIDR for
the rule. Therefore, although the backup subnet has a route rule that uses All
<region> Services in Oracle Services Network, the subnet can have a security
rule that uses OCI <region> Object Storage. See Rule Required Specifically for the
Backup Network.
This section lists the security rules to use with your Exadata system. Security rules control the
types of traffic allowed for the client network and backup network of the Exadata's compute
nodes. The rules are divided into three sections.
There are different ways to implement these rules. For more information, see Ways to
Implement the Security Rules.
RULES REQUIRED FOR BOTH THE CLIENT NETWORK AND BACKUP NETWORK
This section has several general rules that enable essential connectivity for hosts in the VCN.
If you use security lists to implement your security rules, be aware that the rules that follow
are included by default in the default security list. Update or replace the list to meet your
particular security needs. The two ICMP rules (general ingress rules 2 and 3) are required for
proper functioning of network traffic within the Oracle Cloud Infrastructure environment.
Adjust the general ingress rule 1 (the SSH rule) and the general egress rule 1 to allow traffic
only to and from hosts that require communication with resources in your VCN.
General ingress rule 3: Allows connectivity error messages within the VCN
This rule enables the hosts in the VCN to receive connectivity error messages from each
other.
The following security rules are important for the client network.
Important
Client ingress rule 1: Allows ONS and FAN traffic from within the client subnet
The first rule is recommended and enables the Oracle Notification Services (ONS) to
communicate about Fast Application Notification (FAN) events.
Client ingress rule 2: Allows SQL*NET traffic from within the client subnet
This rule is for SQL*NET traffic and is required in these cases:
Client ingress rule 3: Allows all TCP traffic inside the client subnet
l Stateless: No (all rules must be stateful)
l Source Type: CIDR
l Source CIDR: Client subnet's CIDR
l IP Protocol: TCP
l Source Port Range: All
l Destination Port Range: All
l Description: An optional description of the rule.
Client ingress rule 4: Allows all ICMP traffic inside the client subnet
l Stateless: No (all rules must be stateful)
l Source Type: CIDR
Client egress rule 1: Allows all TCP traffic inside the client subnet
l Stateless: No (all rules must be stateful)
l Destination Type: CIDR
l Destination CIDR: Client subnet's CIDR
l IP Protocol: TCP
l Source Port Range: All
l Destination Port Range: All
l Description: An optional description of the rule.
Client egress rule 2: Allows all ICMP traffic inside the client subnet
l Stateless: No (all rules must be stateful)
l Destination Type: CIDR
l Destination CIDR: Client subnet's CIDR
l IP Protocol: ICMP
l Type and Code: All
l Description: An optional description of the rule.
Client egress rule 3: Allows all egress traffic (allows connections to the Oracle
YUM repos)
Client egress rule 3 is important because it allows connections to the Oracle YUM repos. It is
redundant with the general egress rule in Rules Required for Both the Client Network and
Backup Network (and in the default security list). It is optional but recommended in case the
general egress rule (or default security list) is inadvertently changed.
The following security rule is important for the backup network because it enables the DB
system to communicate with Object Storage through the service gateway (and optionally with
the Oracle YUM repos if the client network doesn't have access to them). It is redundant with
the general egress rule in Rules Required for Both the Client Network and Backup Network
(and in the default security list). It is optional but recommended in case the general egress
rule (or default security list) is inadvertently changed.
The Networking service offers two ways to implement security rules within your VCN:
For a comparison of the two methods, see Comparison of Security Lists and Network Security
Groups.
1. Create an NSG for the client network. Add the following security rules to that NSG:
l The rules listed in Rules Required for Both the Client Network and Backup Network
l The rules listed in Rules Required Specifically for the Client Network
2. Create a separate NSG for the backup network. Add the following security rules to that
NSG:
l The rules listed in Rules Required for Both the Client Network and Backup Network
l The rules listed in Rule Required Specifically for the Backup Network
3. When the database administrator creates the Exadata DB system, they must choose
several networking components (for example, which VCN and subnets to use):
l When they choose the client subnet, they can also choose which NSG or NSGs to
use. Make sure they choose the client network's NSG.
l When they choose the backup subnet, they can also choose which NSG or NSGs to
use. Make sure they choose the backup network's NSG.
You could instead create a separate NSG for the general rules. Then when the database
administrator chooses which NSGs to use for the client network, make sure they choose both
the general NSG and the client network NSG. Similarly for the backup network, they choose
both the general NSG and the backup network NSG.
Later when the database administrator creates the Exadata DB system, they must choose
several networking components. When they select the client subnet and backup subnet that
you've already created and configured, the security rules are automatically enforced for the
nodes created in those subnets.
Warning
When you create an Oracle Exadata DB system using the Console or the API, the system is
provisioned to support Oracle databases. The service creates an initial database based on the
options you provide and some default options described later in this topic.
Warning
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: The policy in Let database admins manage DB systems lets the specified
group do everything with databases and related Database resources.
If you're new to policies, see Getting Started with Policies and Common Policies. If you want
to dig deeper into writing policies for databases, see Details for the Database Service.
Prerequisites
l The public key, in OpenSSH format, from the key pair that you plan to use for
connecting to the DB System via SSH. A sample public key, abbreviated for readability,
is shown below.
ssh-rsa AAAAB3NzaC1yc2EAAAABJQAA....lo/gKMLVM2xzc1xJr/Hc26biw3TXWGEakrK1OQ== rsa-key-20160304
To simplify launching a DB system in the Console and when using the API, the following
default options are used for the initial database.
For a list of the database options that you can set in the Console, see To create an Exadata DB
system.
Exadata shapes
Exadata X8 shapes:
o Exadata.Quarter3.100: Provides a 2-node Exadata DB system with up to
100 CPU cores, and 149 TB of usable storage.
o Exadata.Half3.200: Provides a 4-node Exadata DB system with up to 200
CPU cores, and 299 TB of usable storage.
o Exadata.Full3.400: Provides an 8-node Exadata DB system with up to 400
CPU cores, and 598 TB of usable storage.
Exadata X7 shapes:
o Exadata.Quarter2.92: Provides a 2-node Exadata DB system with up to 92
CPU cores, and 106 TB of usable storage.
o Exadata.Half2.184: Provides a 4-node Exadata DB system with up to 184
CPU cores, and 212 TB of usable storage.
o Exadata.Full2.368: Provides an 8-node Exadata DB system with up to 368
CPU cores, and 424 TB of usable storage.
Exadata X6 shapes:
o Exadata.Quarter1.84: Provides a 2-node Exadata DB system with 22
enabled CPU cores, with up to 62 additional CPU cores, and 84 TB of usable
storage.
o Exadata.Half1.168: Provides a 4-node Exadata DB system with 44
enabled CPU cores, with up to 124 additional CPU cores, and 168 TB of
usable storage.
o Exadata.Full1.336: Provides an 8-node Exadata DB system with 88
enabled CPU cores, with up to 248 additional CPU cores, and 336 TB of
usable storage.
Exadata base system:
Important
l Add public SSH keys: The public key portion of each key pair you want to use
for SSH access to the DB system. You can browse or drag and drop .pub files, or
paste in individual public keys. To paste multiple keys, click + Another SSH
Key, and supply a single key for each entry.
l Choose a license type: The type of license you want to use for the DB system.
Your choice affects metering for billing.
o License Included means the cost of the cloud service includes a license
for the Database service.
o Bring Your Own License (BYOL) means you are an Oracle Database
customer with an Unlimited License Agreement or Non-Unlimited License
Agreement and want to use your license with Oracle Cloud Infrastructure.
This removes the need for separate on-premises licenses and cloud
licenses.
4. Specify the network information:
l Virtual Cloud Network: The VCN in which to launch the DB system. Click
Change Compartment to select a VCN in a different compartment.
l Client subnet: The subnet to which the Exadata DB system should attach. Click
Change Compartment to select a subnet in a different compartment.
Do not use a subnet that overlaps with 192.168.16.16/28, which is used by the
Oracle Clusterware private interconnect on the database instance. Specifying an
overlapping subnet will cause the private interconnect to malfunction.
l Backup subnet: The subnet to use for the backup network, which is typically
used to transport backup information to and from Oracle Cloud
InfrastructureObject Storage, and for Data Guard replication. Click Change
Compartment to select a subnet in a different compartment, if applicable.
Do not use a subnet that overlaps with 192.168.128.0/20. This restriction applies
to both the client subnet and backup subnet.
If you plan to back up databases to Object Storage, see the network prerequisites
in Managing Exadata Database Backups.
l Network Security Groups: Optionally, you can specify one or more network
security groups (NSGs) for both the client and backup networks. NSGs function as
virtual firewalls, allowing you to apply a set of ingress and egress security rules
to your DB system. A maximum of five NSGs can be specified. For more
information, see Network Security Groups and Network Setup for Exadata DB
Systems.
Note that if you choose a subnet with a security list, the security rules for the DB
system will be a union of the rules in the security list and the NSGs.
To use network security groups:
o Check the Use Network Security Groups to Control Client Traffic
check box. Note that you must have a virtual cloud network selected to be
able to assign NSGs to your DB system.
o Specify the NSG to use with the client network. You might need to use more
than one NSG. If you're not sure, contact your network administrator.
o To use additional NSGs with the client network, click + Another Network
Security Group.
o Check the Use Network Security Groups to Control Backup Traffic
check box.
o Specify the NSG to use with the backup network. You might need to use
more than one NSG. If you're not sure, contact your network administrator.
o To use additional NSGs with the backup network, click + Another
Network Security Group.
l Hostname prefix: Your choice of host name for the Exadata DB system. The
host name must begin with an alphabetic character, and can contain only
alphanumeric characters and hyphens (-). The maximum number of characters
allowed for an Exadata DB system is 12.
Important
l Host domain name: The domain name for the DB system. If the selected subnet
uses the Oracle-provided Internet and VCN Resolver for DNS name resolution,
this field displays the domain name for the subnet and it can't be changed.
Otherwise, you can provide your choice of a domain name. Hyphens (-) are not
permitted.
If you plan to store database backups in Object Storage, Oracle recommends that
you use a VCN Resolver for DNS name resolution for the client subnet because it
automatically resolves the Swift endpoints used for backups.
l Host and domain URL: Combines the host and domain names to display the
fully qualified domain name (FQDN) for the database. The maximum length is 64
characters.
5. Click Show Advanced Options to specify advanced options for the DB system:
l Disk redundancy: Exadata DB systems support only high redundancy (3-way
mirroring).
l Time zone: The default time zone for the DB system is UTC, but you can specify
a different time zone. The time zone options are those supported in both the
Java.util.TimeZone class and the Oracle Linux operating system. For more
information, see DB System Time Zone.
Tip
l Tags: Optionally, you can apply 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.
6. After you completed the network configuration and any advanced options, click Next.
7. Provide information for the initial database:
l Database name: The name for the database. The database name must begin
with an alphabetic character and can contain a maximum of eight alphanumeric
characters. Special characters are not permitted.
l Database version: The version of the initial database created on the DB system
when it is launched. After the DB system is active, you can create additional
databases on it. You can mix database versions on the DB system.
Note
l PDB name: Not applicable to version 11.2.0.4. The name of the pluggable
database. The PDB name must begin with an alphabetic character, and can
contain a maximum of 8 alphanumeric characters. The only special character
permitted is the underscore ( _).
l Create administrator credentials: A database administrator SYS user will be
created with the password you supply.
o Username: SYS
o Password: Supply the password for this user. The password must meet the
following criteria:
A strong password for SYS, SYSTEM, TDE wallet, and PDB Admin. The
password must be 9 to 30 characters and contain at least two uppercase,
two lowercase, two numeric, and two special characters. The special
characters must be _, #, or -. The password must not contain the username
(SYS, SYSTEM, and so on) or the word "oracle" either in forward or
reversed order and regardless of casing.
o Confirm password: Re-enter the SYS password you specified.
l Select workload type: Choose the workload type that best suits your
application:
o Online Transactional Processing (OLTP) configures the database for a
transactional workload, with a bias towards high volumes of random data
access.
o Decision Support System (DSS) configures the database for a decision
support or data warehouse workload, with a bias towards large data
scanning operations.
l Configure database backups: Specify the settings for backing up the database
to Object Storage:
o Enable automatic backups: Check the check box to enable automatic
incremental backups for this database.
o Backup retention period: (Optional) If you enable automatic backups,
you can choose one of the following preset retention periods: 7 days, 15
days, 30 days, 45 days, or 60 days. The default selection is 30 days.
o Backup Scheduling: If you enable automatic backups, you can choose a
two-hour scheduling window to control when backup operations begin. If
you do not specify a window, the six-hour default window of 00:00 to 06:00
(in the time zone of the DB system's region) is used for your database. See
Automatic Incremental Backups for more information.
l Click Show Advanced Options to specify advanced options for the initial
database:
o Character set: The character set for the database. The default is
AL32UTF8.
o National character set: The national character set for the database. The
default is AL16UTF16.
8. Click Create DB System.
The DB system appears in the list with a status of Provisioning. The DB system's icon
changes from yellow to green (or red to indicate errors).
After the DB system's icon turns green, with a status of Available, you can click the
highlighted DB system name to see details about the DB system. Note the IP addresses.
You'll need the private or public IP address, depending on network configuration, to
connect to the DB system.
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.
DB systems:
l GetDbSystem
l LaunchDbSystem
l ListDbSystems
Database homes:
l CreateDbHome
l GetDbHome
l ListDbHomes
l ListDbSystemShapes
l ListDbVersions
All the traffic in an Exadata DB system is, by default, routed through the data network. To
route backup traffic to the backup interface (BONDETH1), you need to configure a static route
on each of the compute nodes in the cluster. For instructions, see Node Access to Object
Storage: Static Route.
DNS lets you use host names instead of IP addresses to communicate with a DB system. You
can use the Internet and VCN Resolver (the DNS capability built into the VCN) as described in
DNS in Your Virtual Cloud Network. Oracle recommends using a VCN Resolver for DNS name
resolution for the client subnet. It automatically resolves the Swift endpoints required for
backing up databases, patching, and updating the cloud tooling on an Exadata DB system.
Maintaining a secure Exadata DB system in the best working order requires you to perform
the following tasks regularly:
l Patching the Oracle Grid Infrastructure and Oracle Database software on the Exadata
compute nodes. See Patching an Exadata DB System Manually and Oracle Clusterware
Configuration and Administration for information and instructions.
l Updating the operating system and the tooling on the compute nodes. See Updating an
Exadata DB System for information and instructions.
In addition to the maintenance tasks you perform, Oracle manages the patching and updating
of all other infrastructure components, including the physical compute nodes (Dom0), the
Exadata storage servers, and the Exadata InfiniBand switches. This is referred to as DB
system infrastructure maintenance.
Infrastructure maintenance begins with patching of the Exadata compute nodes. Compute
nodes are updated in a rolling fashion, with a single node being shut down, patched, and then
brought back online while other nodes remain operational. This process continues until all
nodes are patched. After compute node patching completes, Oracle patches the storage
nodes. Storage server patching does not impact compute node availability.
Note that while databases are expected to be available during the patching process, Oracle
does not verify that all database services and pluggable databases are available after a node
is brought back online, as these can depend on the application service definition. Oracle
recommends reviewing the documentation on workload management, application continuity,
and client failover best practices to reduce the potential for an outage with your applications.
By following the documentation's guidelines, the impact of infrastructure patching will be only
minor service degradation due to connection loss as compute nodes are sequentially patched.
Oracle recommends that you follow the Maximum Availability Architecture (MAA) best
practices and use Data Guard to ensure the highest availability for your critical applications.
For databases with Data Guard enabled, Oracle recommends that you separate the patching
windows for the infrastructure instances running the primary and standby databases, and
perform a switchover prior to the maintenance operations for the infrastructure instance
hosting the primary database. This allows you to avoid any impact to your primary database
during infrastructure patching.
Typically, Exadata compute nodes require 1.5 hours each for patching, and storage servers
require 1 hour each.
Tip
Exadata Cloud Service updates are released on a quarterly basis. You can set a maintenance
window to determine the time your quarterly infrastructure maintenance will begin. You can
also view scheduled maintenance runs and the maintenance history of your DB system in the
Oracle Cloud Infrastructure Console. For more information, see the following:
In exceptional cases, Oracle might need to update your system apart from the regular
quarterly updates to apply time-sensitive changes such as security updates. While you cannot
opt out of these infrastructure updates, Oracle alerts you in advance through the Cloud
Notification Portal to help you plan for them.
The lifecycle state of your DB system allows you to monitor when the patching of your DB
system begins and ends. In the Oracle Cloud Infrastructure Console, you can see lifecycle
state details messages on the DB System Details page when a tooltip is displayed beside the
Status field. You can also access these messages using the ListDbSystems API, and using
tools based on the API, including SDKs and the OCI CLI. The following OCI CLI command
allows you to list your DB systems: oci db system get --db-system-id <ocid>.
l If you specify a maintenance window, patching begins at your specified start time. The
patching process starts with a series of prerequisite checks to ensure that your system
can be successfully patched. These checks take approximately 30 minutes to complete.
While the system is performing the checks, the lifecycle state remains "Available," and
there is no lifecycle state message.
For example, if you specify that patching should begin at 8:00 a.m., Oracle begins
patching operations at 8:00, but your system's lifecycle state does not change from
"Available" to "Maintenance in Progress" until approximately 8:30 a.m.
l When Exadata compute node patching starts, the DB system lifecycle state is
"Maintenance in Progress", and the associated lifecycle state message is "The
underlying infrastructure of this dbsystem (dbnodes) is being updated."
l When cell storage patching starts, the DB system lifecycle state is "Maintenance in
Progress", and the associated lifecycle state message is "The underlying infrastructure
of this dbsystem (cell storage) is being updated and this will not impact Database
availability."
l After cell patching is complete, the Infiniband switches are patched one at a time, in a
rolling fashion.
l When patching is complete, the DB system lifecycle state is "Available", and the Console
and API-based tools do not provide a lifecycle state message.
For information about the update policy, and details such as the duration and impact on your
system's availability and performance, see Oracle Database Cloud Exadata Service Supported
Software Versions and Planning for Updates.
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: The policy in Let database admins manage DB systems lets the specified
group do everything with databases and related Database resources.
If you're new to policies, see Getting Started with Policies and Common Policies. If you want
to dig deeper into writing policies for databases, see Details for the Database Service.
l Starting: Yellow icon. The database node is being powered on by the start or
reboot action in the Console or API.
l Stopping: Yellow icon. The database node is being powered off by the stop or
reboot action in the Console or API.
l Stopped: Yellow icon. The database node was powered off by the stop action in
the Console or API.
You can also check the status of DB systems and database nodes using the ListDbSystems or
ListDbNodes API operations, which return the lifecycleState attribute.
Note
You can also scale an X8 or X7 Exadata DB system, or an Exadata base system, down to zero
(0) CPU cores to temporarily stop the system and be charged only for the hardware
infrastructure. For more information about scaling down, see Scaling Within an Exadata
System. Oracle recommends that if you are not scaling down to a stopped system (0 cores),
that you scale to at least 3 cores per node.
CPU cores must be scaled symmetrically across all nodes in the DB system. Use multiples of
two for a base system or quarter rack, multiples of four for a half rack, and multiples of eight
for a full rack. The total number of CPU cores in a rack must not exceed the maximum limit
for that shape.
Tip
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
A list of DB systems is displayed.
3. In the list of DB systems, find the system you want to scale and click its highlighted
name.
The system details are displayed.
4. Click Scale CPU Cores and then change the number in the CPU Core Count field. The
text below the field indicates the acceptable values, based on the shape used when the
DB system was launched.
5. Click Update.
Note
Note
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
A list of DB systems is displayed.
3. In the list of DB systems, find the system you want to move and click its highlighted
name.
The system details are displayed.
4. Click Move Resource.
5. Select the new compartment.
6. Click Move Resource.
For information about dependent resources for Database resources, see Moving
Database Resources to a Different Compartment.
Note
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
A list of DB systems is displayed.
3. For the DB system you want to terminate, click the Actions icon (three dots), and then
click Terminate.
4. Confirm when prompted.
The DB system's icon indicates Terminating.
At this point, you cannot connect to the system and any open connections are terminated.
To edit the network security groups (NSGs) for your client or backup network
Your client and backup networks can each use up to five network security groups (NSGs).
Note that if you choose a subnet with a security list, the security rules for the DB system will
be a union of the rules in the security list and the NSGs. For more information, see Network
Security Groups and Network Setup for Exadata DB Systems.
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
A list of DB systems is displayed.
3. In the list of DB systems, find the system you want to manage and click its highlighted
name.
The system details are displayed.
4. In the Network details, click the Edit link to the right of the Client Network Security
Groups or Backup Network Security Groups field.
5. In the Edit Network Security Groups dialog, click + Another Network Security
Group to add an NSG to the network.
To change an assigned NSG, click the drop-down menu displaying the NSG name, then
select a different NSG.
To remove an NSG from the network, click the X icon to the right of the displayed NSG
name.
6. Click Save.
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
A list of DB systems is displayed.
3. In the list of DB systems, find the system you want to scale and click its highlighted
name.
The system details are displayed.
4. Click Scale CPU Cores, and then change the number.
Note
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
3. In the list of DB systems, find the DB system you want to administer and click its
highlighted name.
4. On the DB system details page, click Update License Type.
The dialog displays the options with your current license type selected.
5. Select the new license type.
6. Click Save.
3. Find the DB system or database resource you're interested in, and click the name.
4. In the Resources section, click Work Requests. The status of all work requests
appears on the page.
5. To see the log messages, error messages, and resources that are associated with a
specific work request, click the operation name. Then, select an option in the More
information section.
For associated resources, you can click the Actions icon (three dots) next to a resource
to copy the resource's OCID.
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
A list of DB systems is displayed.
3. In the list of DB systems, find the system you want to set the maintenance window for
and click its highlighted name.
The system details are displayed.
4. On the DB system details page, under Maintenance, click the edit link in the
Maintenance Schedule field.
5. In the Automatic Maintenance Schedule dialog, select Specify a schedule.
6. Under Maintenance months, specify at least one month for each quarter during which
Exadata infrastructure maintenance will take place. You can select more than one
month per quarter. If you specify a long lead time for advanced notification (for
example, 4 weeks), you may wish to specify 2 or 3 months per quarter during which
maintenance runs can occur. This will ensure that your maintenance updates are applied
in a timely manner after accounting for your required lead time.
7. Under Week of the month, specify which week of the month maintenance will take
place. Weeks start on the 1st, 8th, 15th, and 22nd days of the month, and have a
duration of 7 days. Weeks start and end based on calendar dates, not days of the week.
Maintenance cannot be scheduled for the fifth week of months that contain more than 28
days.
8. Optional. Under Day of the week, specify the day of the week on which the
maintenance will occur. If you do not specify a day of the week, Oracle will run the
maintenance update on a weekend day to minimize disruption.
9. Optional. Under Start hour, specify the hour during which the maintenance run will
begin. If you do not specify a start hour, Oracle will pick the least disruptive time to run
the maintenance update.
10. Under Lead Time, specify the number of weeks ahead of the maintenance event you
would like to receive a notification message. Your lead time ensures that a newly
released maintenance update is scheduled to account for your required period of
advanced notification.
11. Update Maintenance Schedule.
To view or edit the time of the next scheduled maintenance for Exadata DB
system infrastructure
This task describes how to view the maintenance schedule for an Exadata DB system's
infrastructure. See Oracle Managed Infrastructure Maintenance Updates for more information
on this type of maintenance.
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
A list of DB systems is displayed.
3. In the list of DB systems, find the system you want to set the maintenance window for
and click its highlighted name.
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
A list of DB systems is displayed.
3. In the list of DB systems, find the system you want to set the maintenance window for
and click its highlighted name.
The system details are displayed.
4. On the DB system details page, under Maintenance, click the view link in the Next
Maintenance field.
5. Click Maintenance History to see a list of past maintenance events including details
on their completion state.
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.
DB systems:
l GetDbSystem
l ListDbSystems
l ChangeDbSystemCompartment
l TerminateDbSystem
l UpdateDbSystem
Nodes:
About IORM
The I/O Resource Management (IORM) feature allows you to manage how multiple databases
share the I/O resources of an Oracle Exadata DB system.
On an Exadata DB system, all databases share dedicated storage servers which include flash
storage. By default, the databases are given equal priority with respect to these resources.
The Exadata storage management software uses a first come, first served approach for query
processing. If a database executes a major query that overloads I/O resources, overall
system performance can be slowed down.
IORM allows you to assign priorities to your databases to ensure critical queries are processed
first when workloads exceed their resource allocations. You assign priorities by creating
directives that specify the number of shares for each database. The number of shares
corresponds to a percentage of resources given to that database when I/O resources are
stressed.
Directives work together with an overall optimization objective you set for managing the
resources. The following objectives are available:
For more information about IORM, see Exadata System Software User's Guide.
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: The policy in Let database admins manage DB systems lets the specified
group do everything with databases and related Database resources.
If you're new to policies, see Getting Started with Policies and Common Policies. If you want
to dig deeper into writing policies for databases, see Details for the Database Service.
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
3. In the list of DB systems, find the Exadata DB system for which you want to enable
IORM, and click its highlighted name.
The system details are displayed, showing the IORM status as "Disabled."
4. Cick Enable IORM.
It might take a minute for the Enable I/O Resource Management dialog to retrieve the
DB system information.
5. Select the objective to apply to the resource plan:
l Auto - (Recommended) Dynamically changes the objective based on the resource
plan and observed workloads.
l Balanced - Weighs high throughput and low latency evenly.
l High throughput - Provides the best throughput for DSS workloads.
l Low latency - Provides the best latency for critical OLTP workloads.
6. Configure the resource plan default directive by setting the number of shares. This
number of shares is assigned to each database not associated with a specific directive.
7. In the Resource Plan Directives section, add a directive for each database you want to
assign a greater or lesser number of shares than the default directive.
To add a directive, click + Additional Directive, then specify the database and the
number of shares for that database.
8. When you are done adding directives, click Enable.
While the IORM configuration settings are being applied, the system details page shows
the IORM status as "Updating." The update might take several minutes to complete but
should have no impact on your ability to perform normal operations on your DB system.
After a successful update, the IORM status shows as "Enabled."
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
3. In the list of DB systems, find the Exadata DB system for which you want to modify the
IORM configuration, and click its highlighted name.
The system details are displayed, showing the IORM status as "Enabled."
4. Click Update IORM.
5. In the Update I/O Resource Management dialog, take one of the following actions:
l Change your settings - Specify a new objective and adjust your directives, as
applicable, and then click Update.
l Disable IORM - Click Disable IORM. Disabling IORM removes all your resource
plan directives and restores a basic objective for I/O resource management.
While the new IORM configuration settings are being applied, the system details page
shows the IORM status as "Updating." The update might take several minutes to
complete but should have no impact on your ability to perform normal operations on
your DB system. After a successful update, the IORM status shows as "Enabled" or
"Disabled," depending on the action you took.
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.
Use these API operations to manage the I/O resources of your Exadata DB system.
l ListDbSystems
l GetDbSystem
l GetExadataIormConfig
l UpdateExadataIormConfig
Prerequisites
For SSH access to a compute node in an Exadata DB System, you'll need the following:
l The full path to the file that contains the private key associated with the public key used
when the system was launched.
l The public or private IP address of the DB System. Use the private IP address to
connect to the DB system from your on-premises network, or from within the virtual
cloud network (VCN). This includes connecting from a host located on-premises
connecting through a VPN or FastConnect to your VCN, or from another host in the same
VCN. Use the DB System's public IP address to connect to the system from outside the
cloud (with no VPN). You can find the IP addresses in the Oracle Cloud Infrastructure
Console on the DB System Details page by clicking Nodes under the Resources list.
The values are displayed in the Public IP Address and Private IP Address & DNS
Name columns of the Nodes table.
You can connect to the compute nodes in an Exadata DB System by using a Secure Shell (SSH)
connection. Most UNIX-style systems (including Linux, Solaris, BSD, and OS X) include an
SSH client by default. For Windows, you can download a free SSH client called PuTTY from
http://www.putty.org.
<private key> is the full path and name of the file that contains the private key associated
with the Exadata DB System you want to access.
Use the private or public IP address depending on your network configuration. For more
information, see Prerequisites.
3. In the Category pane, expand Connection, expand SSH, and then click Auth, and
browse to select your private key.
4. Optionally, return to the Session category screen and save this session information for
reuse later.
5. Click Open to start the session.
In the following example, the host name is "ed1db01" and the database name is
"cdb01".
[oracle@ed1db01]# . cdb01.env
You can connect to a database with SQL Developer by using one of the following methods:
l Create a temporary SSH tunnel from your computer to the database. This method
provides access only for the duration of the tunnel. (When you are done using the
database, be sure to close the SSH tunnel by exiting the SSH session.)
l Open port 1521 for the Oracle default listener by updating the security list used for the
DB System. This method provides more durable access to the database. For more
information, see Updating the Security List.
After you've created an SSH tunnel or opened port 1521 as described above, you can connect
to a Exadata DB System using SCAN IP addresses or public IP addresses, depending on how
your network is set up and where you are connecting from. You can find the IP addresses in
l Use the private SCAN IP addresses, as shown in the following tnsnames.ora example:
testdb=
(DESCRIPTION =
(ADDRESS_LIST=
(ADDRESS = (PROTOCOL = TCP)(HOST = <scanIP1>)(PORT = 1521))
(ADDRESS = (PROTOCOL = TCP)(HOST = <scanIP2>)(PORT = 1521)))
(CONNECT_DATA =
(SERVER = DEDICATED)
(SERVICE_NAME = <dbservice.subnetname.dbvcn.oraclevcn.com>)
)
)
l Define an external SCAN name in your on-premises DNS server. Your application can
resolve this external SCAN name to the DB System's private SCAN IP addresses, and
then the application can use a connection string that includes the external SCAN name.
In the following tnsnames.ora example, extscanname.example.com is defined in the
on-premises DNS server.
testdb =
(DESCRIPTION =
(ADDRESS = (PROTOCOL = TCP)(HOST = <extscanname.example.com>)(PORT = 1521))
(CONNECT_DATA =
(SERVER = DEDICATED)
(SERVICE_NAME = <dbservice.subnetname.dbvcn.oraclevcn.com>)
)
)
are in different VCNs, or if the database is on a VCN that has an internet gateway. However,
there are important implications to consider:
l When the client uses the public IP address, the client bypasses the SCAN listener and
reaches the node listener, so server side load balancing is not available.
l When the client uses the public IP address, it cannot take advantage of the VIP failover
feature. If a node becomes unavailable, new connection attempts to the node will hang
until a TCP/IP timeout occurs. You can set client side sqlnet parameters to limit the
TCP/IP timeout.
The following tnsnames.ora example shows a connection string that includes the CONNECT_
TIMEOUT parameter to avoid TCP/IP timeouts.
test=
(DESCRIPTION =
(CONNECT_TIMEOUT=60)
(ADDRESS_LIST=
(ADDRESS = (PROTOCOL = TCP)(HOST = <publicIP1>)(PORT = 1521))
(ADDRESS = (PROTOCOL = TCP)(HOST = <publicIP2>)(PORT = 1521))
)
(CONNECT_DATA =
(SERVER = DEDICATED)
(SERVICE_NAME = <dbservice.subnetname.dbvcn.oraclevcn.com>)
)
)
When you create a new Exadata DB system database with a new Oracle Home (Database
Home) directory location, the Oracle Database binaries are sourced from a software image
that is stored on your Exadata DB system. Over time, the software images on your Exadata
DB system become outdated if they are not maintained. Using an outdated software image
makes it necessary for you to apply patches to newly installed binaries to bring them up to
date. Oracle recommends that you maintain your Exadata DB system environment with up-to-
date software images to avoid this extra patching step which can be time-consuming and
error prone.
You can view information about Oracle Database software images that are available to
download to your Exadata DB system by using the cswlib list subcommand of the dbaascli
utility.
The command displays a list of available software images, including version and bundle
patch information that you can use to download the software image.
4. Exit the root-user command shell:
# exit
$
You can download available software images onto your Exadata DB system by using the
cswlib download subcommand of the dbaascli utility.
The command displays a list of software images that are downloaded to your Exadata
Cloud Service environment, including version and bundle patch information.
The optional parameters are:
l version: specifies an Oracle Database software version. For example, 19000,
18000, or 12201.
l bp: identifies a bundle patch release. For example, APR2019, JAN2019, or
OCT2018.
If you do not include the optional parameters, the dbaascli cswlib download
command downloads the latest available software image for all available Oracle
Database software versions.
4. Exit the root-user command shell:
# exit
$
OS Updates
Important
You update the operating systems of Exadata compute nodes by using the patchmgr tool. This
utility manages the entire update of one or more compute nodes remotely, including running
pre-reboot, reboot, and post-reboot steps. You can run the utility from either an Exadata
compute node or a non-Exadata server running Oracle Linux. The server on which you run the
utility is known as the "driving system." You cannot use the driving system to update itself.
Therefore, if the driving system is one of the Exadata compute nodes on a system you are
updating, you must run a separate operation on a different driving system to update that
server.
The following two scenarios describe typical ways of performing the updates:
The simplest way to run the update the Exadata system is to use a separate Oracle Linux
server to update all Exadata compute nodes in the system.
You can use one Exadata compute node to drive the updates for the rest of the compute nodes
in the system, and then use one of the updated nodes to drive the update on the original
Exadata driver node.
For example: You are updating a half rack Exadata system, which has four compute nodes -
node1, node2, node3, and node4. First, use node1 to drive the updates of node2, node3, and
node4. Then, use node2 to drive the update of node1.
The driving system requires root user SSH access to each compute node the utility will update.
Warning
l Before you begin your updates, review Exadata Cloud Service Software Versions (Doc
ID 2333222.1) to determine the latest software version and target version to use.
l Some steps in the update process require you to specify a YUM repository. The YUM
repository URL is:
http://yum-<region_identifier>.oracle.com/repo/EngineeredSystems/exadata/dbserver/<latest_
version>/base/x86_64.
Region identifiers are text strings used to identify Oracle Cloud Infrastructure regions
(for example, us-phoenix-1). You can find a complete list of region identifiers in
Regions.
You can run the following curl command to determine the latest version of the YUM
repository for your DB system region:
This example returns the most current version of the YUM repository for the US West
(Phoenix) region:
curl -s -X GET http://yum-us-phoenix-
1.oracle.com/repo/EngineeredSystems/exadata/dbserver/index.html |egrep "18.1."
<a href="18.1.4.0.0/">18.1.4.0.0/</a> 01-Mar-2018 03:36 -
b. Switch to the grid user, and identify all computes in the cluster.
[root@node1]# su - grid
[grid@node1]$ olsnodes
node1
node1
a. Switch back to the root user on node1, check whether a root ssh key pair (id_rsa
and id_rsa.pub) already exists. If not, then generate it.
[root@node1 .ssh]# ls /root/.ssh/id_rsa*
ls: cannot access /root/.ssh/id_rsa*: No such file or directory
[root@node1 .ssh]# ssh-keygen -t rsa
Generating public/private rsa key pair.
Enter file in which to save the key (/root/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /root/.ssh/id_rsa.
Your public key has been saved in /root/.ssh/id_rsa.pub.
The key fingerprint is:
93:47:b0:83:75:f2:3e:e6:23:b3:0a:06:ed:00:20:a5
[email protected]
The key's randomart image is:
+--[ RSA 2048]----+
|o.. + . |
|o. o * |
|E . o o |
| . . = |
| o . S = |
| + = . |
| + o o |
| . . + . |
| ... |
+-----------------+
b. Distribute the public key to the target nodes, and verify this step. In this example,
the only target node is node2.
[root@node1 .ssh]# scp -i ~opc/.ssh/id_rsa ~root/.ssh/id_rsa.pub opc@node2:/tmp/id_
rsa.node1.pub
id_rsa.pub
c. On the target node (node2, in this example), add the root public key of node1 to
inflating: dbserver_patch_5.180228.2/ibdiagtools/SampleOutputs.txt
inflating: dbserver_patch_5.180228.2/ibdiagtools/infinicheck
inflating: dbserver_patch_5.180228.2/ibdiagtools/ibping_test
inflating: dbserver_patch_5.180228.2/ibdiagtools/tar_ibdiagtools
inflating: dbserver_patch_5.180228.2/ibdiagtools/verify-topology
inflating: dbserver_patch_5.180228.2/installfw_exadata_ssh
creating: dbserver_patch_5.180228.2/linux.db.rpms/
inflating: dbserver_patch_5.180228.2/md5sum_files.lst
inflating: dbserver_patch_5.180228.2/patchmgr
inflating: dbserver_patch_5.180228.2/xcp
inflating: dbserver_patch_5.180228.2/ExadataSendNotification.pm
inflating: dbserver_patch_5.180228.2/ExadataImageNotification.pl
inflating: dbserver_patch_5.180228.2/kernelupgrade_oldbios.sh
inflating: dbserver_patch_5.180228.2/cellboot_usb_pci_path
inflating: dbserver_patch_5.180228.2/exadata.img.env
inflating: dbserver_patch_5.180228.2/README.txt
inflating: dbserver_patch_5.180228.2/exadataLogger.pm
inflating: dbserver_patch_5.180228.2/patch_bug_26678971
inflating: dbserver_patch_5.180228.2/dcli
inflating: dbserver_patch_5.180228.2/patchReport.py
extracting: dbserver_patch_5.180228.2/dbnodeupdate.zip
creating: dbserver_patch_5.180228.2/plugins/
inflating: dbserver_patch_5.180228.2/plugins/010-check_17854520.sh
inflating: dbserver_patch_5.180228.2/plugins/020-check_22468216.sh
inflating: dbserver_patch_5.180228.2/plugins/040-check_22896791.sh
inflating: dbserver_patch_5.180228.2/plugins/000-check_dummy_bash
inflating: dbserver_patch_5.180228.2/plugins/050-check_22651315.sh
inflating: dbserver_patch_5.180228.2/plugins/005-check_22909764.sh
inflating: dbserver_patch_5.180228.2/plugins/000-check_dummy_perl
inflating: dbserver_patch_5.180228.2/plugins/030-check_24625612.sh
inflating: dbserver_patch_5.180228.2/patchmgr_functions
inflating: dbserver_patch_5.180228.2/exadata.img.hw
inflating: dbserver_patch_5.180228.2/libxcp.so.1
inflating: dbserver_patch_5.180228.2/imageLogger
inflating: dbserver_patch_5.180228.2/ExaXMLNode.pm
inflating: dbserver_patch_5.180228.2/fwverify
e. Create the dbs_group file that contains the list of compute nodes to update.
Include the nodes listed after running the olsnodes command in step 1 except for
the driving system node. In this example, dbs_group should include only node2.
Important
*************************************************************************************************
***********
NOTE patchmgr release: 5.180228 (always check MOS 1553103.1 for the latest release of
dbserver.patch.zip)
NOTE
WARNING Do not interrupt the patchmgr session.
WARNING Do not resize the screen. It may disturb the screen layout.
WARNING Do not reboot database nodes during update or rollback.
WARNING Do not open logfiles in write mode and do not try to alter them.
*************************************************************************************************
***********
2018-02-28 21:22:45 +0000 :Working: DO: Initiate precheck on 1 node(s)
2018-02-28 21:24:57 +0000 :Working: DO: Check free space and verify SSH equivalence for
the root user to node2
2018-02-28 21:26:15 +0000 :SUCCESS: DONE: Check free space and verify SSH equivalence for
the root user to node2
2018-02-28 21:26:47 +0000 :Working: DO: dbnodeupdate.sh running a precheck on node(s).
2018-02-28 21:28:23 +0000 :SUCCESS: DONE: Initiate precheck on node(s).
Important
*************************************************************************************************
***********
NOTE patchmgr release: 5.180228 (always check MOS 1553103.1 for the latest release of
dbserver.patch.zip)
NOTE
WARNING Do not interrupt the patchmgr session.
WARNING Do not resize the screen. It may disturb the screen layout.
WARNING Do not reboot database nodes during update or rollback.
WARNING Do not open logfiles in write mode and do not try to alter them.
*************************************************************************************************
***********
2018-02-28 21:29:00 +0000 :Working: DO: Initiate backup on 1 node(s).
2018-02-28 21:29:00 +0000 :Working: DO: Initiate backup on node(s)
2018-02-28 21:29:01 +0000 :Working: DO: Check free space and verify SSH equivalence for
5. Remove all custom RPMs from the target compute nodes that will be updated. Custom
RPMs are reported in precheck results. They include RPMs that were manually installed
after the system was provisioned.
Note
*************************************************************************************************
***********
NOTE patchmgr release: 5.180228 (always check MOS 1553103.1 for the latest release of
dbserver.patch.zip)
NOTE
NOTE Database nodes will reboot during the update process.
NOTE
WARNING Do not interrupt the patchmgr session.
WARNING Do not resize the screen. It may disturb the screen layout.
WARNING Do not reboot database nodes during update or rollback.
WARNING Do not open logfiles in write mode and do not try to alter them.
*************************************************************************************************
********
7. After the update operation completes, verify the version of the kernel on the compute
node that was updated.
[root@node2 ~]# imageinfo -ver
18.1.4.0.0.180125.3
8. If the driving system is a compute node that needs to be updated (as in this example),
repeat steps 2 through 7 of this procedure using an updated compute node as the driving
system to update the remaining compute node. In this example update, you would use
node2 to update node1.
9. On each compute node, run the uptrack-install command as root to install the
available ksplice updates.
uptrack-install --all -y
You can update the cloud-specific tooling included on an Exadata DB system compute node by
downloading and applying an RPM file containing the latest version of the tools.
Note
PREREQUISITE
The compute nodes in the Exadata DB system must be configured to access the Oracle Cloud
Infrastructure Object Storage service. For more information, see Node Access to Object
Storage: Static Route.
The method for updating the tooling depends on the tooling release that is currently installed
on the compute node.
3. Use the following command to display information about the installed cloud tooling and
note the release label, shown in red in the example that follows.
# rpm -qa|grep -i dbaastools_exa
dbaastools_exa-1.0-1+18.1.2.1.0_180511.0801.x86_64
Important
$ sudo -s
#
Example output:
[root@exacs-node1 ]# dbaascli patch tools list
DBAAS CLI version 19.4.1.0.0
Executing command patch tools list
Checking tools on all nodes
Current Patchid on stb-elbdc1: 19.4.1.0.0_190822.1034
Available Patches
Patchid : 19.4.1.0.0_190827.1034
Patchid : 19.4.1.0.0_190912.0440(LATEST)
Install tools patch using
dbaascli patch tools apply --patchid 19.4.1.0.0_190912.0440 or
dbaascli patch tools apply --patchid LATEST
All Nodes have the same tools version
4. In the command response, locate the patch ID of the cloud tooling update. The patch ID
is listed as the "Patchid" value. If multiple patches are listed, choose the latest one.
5. Apply the patch containing the latest cloud tooling update by using one of the following
methods:
l Specify the patch ID of the latest patch:
# dbaascli patch tools apply --patchid <patch_ID>
7. Exit the root-user command shell and disconnect from the compute node:
# exit
$ exit
8. If you are updating cloud tooling on a DB system hosting a Data Guard configuration,
repeat the preceding steps on the compute node of the peer (primary or standby
database's) DB system.
The following example downloads the RPM file from the US West (Phoenix).
wget https://swiftobjectstorage.us-phoenix-1.oraclecloud.com/v1/exadata/patches/dbaas_
patch/shome/dbaastools_exa.rpm
See API Reference and Endpoints for the Swift API endpoint for your region.
2. Apply the RPM file.
# rpm -ev dbaastools_exa
# rpm -ivh dbaastools_exa.rpm
3. Repeat the previous steps on each compute node in the Exadata DB system.
You can configure automatic cloud tooling updates for Exadata DB systems. When you
configure these updates, an entry is added to the /etc/crontab file to regularly check for
cloud tooling updates and apply new updates to the compute node when they become
available.
Note
To check whether automatic cloud tooling updates are enabled for an Exadata
DB system
1. Connect to the compute node as the opc user.
2. Start a root-user command shell:
$ sudo -s
#
3. Use the following command to check whether automatic tooling updates are enabled:
# dbaascli patch tools auto status
If the command response includes "INFO: auto rpm update is enabled", then automatic
updates are enabled. If the response includes "INFO: auto rpm update is disabled", then
automatic updates are disabled.
4. Exit the root-user command shell and disconnect from the compute node:
# exit
$ exit
5. If you are checking the status of automatic cloud tooling updates on a DB system
hosting a Data Guard configuration, repeat the preceding steps on the compute node of
the peer (primary or standby database's) DB system.
4. Exit the root-user command shell and disconnect from the compute node:
# exit
$ exit
5. If you are enabling automatic cloud tooling updates on a DB system hosting a Data
Guard configuration, repeat the preceding steps on the compute node of the peer
(primary or standby database's) DB system.
To run a tooling update on demand when automatic cloud tooling updates are
enabled
You can perform an update at any time between automatic updates by running the dbaascli
patch tools auto enable subcommand. This command checks whether there is a newer
version of the tooling than the version on the compute node and applies the newer version if it
finds one.
3. Use the following command to check for a newer tooling version and apply it:
# dbaascli patch tools auto execute
4. Exit the root-user command shell and disconnect from the compute node:
# exit
$ exit
5. If you are performing the on-demand cloud tooling update on a DB system hosting a
Data Guard configuration, repeat the preceding steps on the compute node of the peer
(primary or standby database's) DB system.
4. Exit the root-user command shell and disconnect from the compute node:
# exit
$ exit
5. If you are disabling automatic cloud tooling updates on a DB system hosting a Data
Guard configuration, repeat the preceding steps on the compute node of the peer
(primary or standby database's) DB system.
Note
Prerequisites
Patches are stored in Oracle Cloud Infrastructure Object Storage, so the Exadata DB system
requires access to that service. To enable this access, Oracle recommends using a service
gateway with the VCN. For more information, see Network Setup for Exadata DB Systems. In
Managing Patches
where:
l --oh specifies a compute node and Oracle home directory for which you want to
list the available patches. In this context, an Oracle home directory may be an
Oracle Database home directory or the Oracle Grid Infrastructure home directory.
Example (Oracle Database):
# dbaascli patch db list --oh exacs-node1:/u02/app/oracle/product/18.0.0.0/dbhome_1
DBAAS CLI version 18.2.3.2.0
Executing command patch db list --oh exacs-node1:/u02/app/oracle/product/18.0.0.0/dbhome_1
INFO : EXACS patching
Available Patches
patchid :29708703 (Database Release Update : 18.7.0.0.190716 (Jul 2019))
Note
To learn more about the patch db list subcommand, including available options,
execute the following command:
# dbaascli patch db list ?
where:
l --patchid identifies the patch to be pre-checked.
l --dbnames specifies the name of the database you want to pre-check.
Example (Oracle Database):
# dbaascli patch db prereq --patchid 29708703 --dbnames DB18
To learn more about the patch db prereq subcommand, including available options,
execute the following command:
# dbaascli patch db prereq ?
To apply a patch
You can apply a patch by using the patch db apply subcommand of the dbaascli utility.
l Can be used to patch some or all of your compute nodes using one command.
l Coordinates multi-node patching in a rolling manner.
l Can execute patch-related SQL after patching all the compute nodes in the cluster.
where:
l --patchid identifies the patch to be applied.
l --dbnames specifies the name of the database you want to apply the patch to.
l --run_datasql 1 instructs the command to execute patch-related SQL
commands.
Note
To learn more about the patch db apply subcommand, including available options,
execute the following command:
# dbaascli patch db apply ?
# exit
$
You can use the opatch utility to determine the patches that have been applied to an Oracle
Database or Grid Infrastructure installation.
/home/oracle
l Can be used to roll back a patch on some or all of your compute nodes using one
command.
l Coordinates multi-node operations in a rolling manner.
l Can execute rollback-related SQL after rolling back the patch on all the compute nodes
in the cluster.
where:
l --patchid identifies the patch to be rolled back.
l --instanceN specifies a compute node and one or more Oracle home directories
that are subject to the rollback operation. In this context, an Oracle home
directory may be an Oracle Database home directory or the Oracle Grid
Infrastructure home directory.
l --dbnames specifies the name of the database you want to apply the switchback
operation to.
Note
For information and instructions on patching the system by using the dbaascli utility, see
Patching an Exadata DB System Manually.
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: The policy in Let database admins manage DB systems lets the specified
group do everything with databases and related Database resources.
If you're new to policies, see Getting Started with Policies and Common Policies. If you want
to dig deeper into writing policies for databases, see Details for the Database Service.
Patching an Exadata DB system updates the components on all the compute nodes on that
system. A DB system patch updates the grid infrastructure (GI) and a Database Home patch
updates the Oracle Database software shared by the databases in that home. Thus, you patch
a database by either moving it to a Database Home that has the correct patch version or you
patch the Database Home the database is currently in.
l Back up your databases before you apply any patches. For information about backing up
the databases, see Managing Exadata Database Backups.
l Patch a DB system before you patch the Databases Homes and databases on that
system.
l Before you apply any patch, run the precheck operation to ensure your DB system or
Database Home meets the requirements for that patch.
l To patch a database to a version other than the database version of the current home,
move the database to a Database Home running the target version. This technique
requires less downtime and allows you to easily roll back the database to the previous
version by moving it back to the old Database Home. See To patch a database by
moving it to another Database Home.
Prerequisites
The DB system requires access to the Oracle Cloud Infrastructure Object Storage service,
including connectivity to the applicable Swift endpoint for Object Storage. Oracle recommends
using a service gateway with the VCN to enable this access. For more information, see these
topics:
l Network Setup for Exadata DB Systems: For information about setting up your VCN for
the DB system, including the service gateway.
l https://cloud.oracle.com/infrastructure/storage/object-storage/faq: For information
about the Swift endpoints to use.
Important
You can use the Console to view the history of patch operations on Exadata DB systems and
Database Homes, apply patches, and monitor the status of patch operations.
6. Click the Actions icon (three dots) for the patch you are interested in, and then click one
of the following actions:
l Run Precheck: Check for any prerequisites to make sure that the patch can be
successfully applied.
l Apply Patch: Applies the selected patch. Oracle highly recommends that you run
the precheck operation for a patch before you apply it.
7. Confirm when prompted.
The patch list displays the status of the operation. While a patch is being applied, the
patch's status displays as Patching and the DB system's status displays as Updating.
Lifecycle operations on the DB system and its resources might be temporarily
unavailable. If patching completes successfully, the patch's status changes to Applied
and the status of the DB system changes to Available. You can view more details about
an individual patch operation by clicking Patch History.
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
3. In the list of DB systems, click the name of the Exadata DB system with the database
you want to move to display the DB system details.
4. In the list of databases, click the name of the database you want to move to display
details about it.
5. Click Move to Another Home.
6. Select the target Database Home.
7. Click Move Database.
8. Confirm the move operation.
The database will be stopped in the current home and then restarted in the destination
home. While the database is being moved, the Database Home status displays as
Moving Database. When the operation completes, Database Home is updated with the
current home. If the operation is unsuccessful, the status of the database displays as
Failed, and the Database Home field provides information about the reason for the
failure.
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
3. In the list of DB systems, click the name of the Exadata DB system with the Database
Home you want to patch to display the DB system details.
4. Under Resources, click Database Homes.
5. Click the name of the Database Home you want to patch to display the Database Home
details.
6. Under Database Software Version, click View.
7. Review the list of available patches for the Database Home.
8. Click the Actions icon (three dots) for the patch you are interested in, and then click one
of the following actions:
l Run Precheck: Check for any prerequisites to make sure that the patch can be
successfully applied.
l Apply Patch: Applies the selected patch. Oracle highly recommends that you run
the precheck operation for a patch before you apply it.
9. Confirm when prompted.
The patch list displays the status of the operation. While a patch is being applied, the
status of the patch displays as Patching and the status of the Database Home and the
databases in it display as Updating. During the operation, each database in the home is
stopped and then restarted. If patching completes successfully, the patch's status
changes to Applied and the Database Home's status changes to Available. You can
view more details about an individual patch operation by clicking Patch History.
Each patch history entry represents an attempted patch operation and indicates whether the
operation was successful or failed. You can retry a failed patch operation. Repeating an
operation results in a new patch history entry.
Patch history views in the Console do not show patches that were applied by using command
line tools such as dbaascli.
3. In the list of DB systems, click the name of the Exadata DB system with the Database
Home you want to view to display the DB system details.
4. Under Resources, click Database Homes.
5. Click the name of the Database Home you want to view to display the Database Home
details.
6. Under Database Software Version, click View.
7. Click Patch History.
The Patch History page displays the history of patch operations for that Database Home
and for the DB system to which it belongs.
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.
Use these API operations to manage patching Exadata DB systems, databases, and Database
Homes.
DB systems:
l ListDbSystemPatches
l ListDbSystemPatchHistoryEntries
l GetDbSystemPatch
l GetDbSystemPatchHistoryEntry
l UpdateDbSystem
Databases:
Database Homes:
l ListDbHomePatches
l ListDbHomePatchHistoryEntries
l GetDbHomePatch
l GetDbHomePatchHistoryEntry
l UpdateDbHome
For the complete list of APIs for the Database service, see Database Service API.
Enterprise Manager Database Express 12c (EM Express) is available on Exadata DB system
database deployments created using Oracle Database 12c Release 1 (12.1) or later.
How you access EM Express depends on whether you want to manage a CDB or PDB.
For both CDBs and PDBs, you must add the port to a security list as described in Updating the
Security List.
To confirm the port that is in use for a specific database, connect to the database as a
database administrator and execute the query shown in the following example:
DBMS_XDB_CONFIG.GETHTTPSPORT()
------------------------------
5502
S ETTING THE PORT FOR EM EXPRESS TO MANAGE A PDB (ORACLE DATABASE 12.1 ONLY)
In Oracle Database 12c Release 1, a unique HTTPS port must be configured for the root
container (CDB) and each PDB that you manage using EM Express.
To configure a HTTPS port so that you can manage a PDB with EM Express:
1. Invoke SQL*Plus and log in to the PDB as the SYS user with SYSDBA privileges.
2. Execute the DBMS_XDB_CONFIG.SETHTTPSPORT procedure.
SQL> exec dbms_xdb_config.sethttpsport(port-number)
ACCESSING EM EXPRESS
Before you access EM Express, add the port to the security list. See Updating the Security List.
After you update the security list, you can access EM Express by directing your browser to the
URL https://<node-ip-address>:<port>/em, where node-ip-address is the public IP
address of the compute node hosting EM Express, and port is the EM Express port used by the
database.
You can confirm the Database Control port for a database by searching for REPOSITORY_URL in
the $ORACLE_HOME/host_sid/sysman/config/emd.properties file.
Before you access Database Control, add the port for the database to the security list
associated with the Exadata DB system's client subnet. For more information, see Updating
the Security List.
After you update the security list, you can access Database Control by directing your browser
to the URL https://<node-ip-address>:<port>/em, where node-ip-address is the public
IP address of the compute node hosting Database Control, and port is the Database Control
port used by the database.
Before you can access EM Express or Database Control, you must add the port for the
database to the security list associated with the Exadata DB system's data (client) subnet. To
update an existing security list, complete the following steps using the Console:
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
A list of DB systems is displayed.
3. Locate the DB system in the list.
4. Note the DB system's Client Subnet name and click its Virtual Cloud Network.
5. Locate the subnet in the list, and then click its security list under Security Lists.
6. Click Edit All Rules and add an ingress rule with source type=CIDR, source
CIDR=<source CIDR>, protocol=TCP, and port=<port number or port range>.
The source CIDR should be the CIDR block that includes the ports you open for the client
connection.
For detailed information about creating or updating a security list, see Security Lists.
When you add a database to an Exadata DB system, the database versions you can select
from depend on the current patch level of that DB system. You might have to patch your DB
system to add later database versions.
After you provision a database, you can move it to another Database Home. Consolidating
databases under the same home can facilitate management of these resources. All databases
in a given Database Home share the Oracle Database binaries and therefore, have the same
database version. The Oracle-recommended way to patch a database to a version that is
different from the current version is to move the database to a home running the target
version. For information about patching the DB system, see Patching an Exadata DB System.
Note
You can also add and remove databases, and perform other management tasks on a database
by using command line utilities. For information and instructions on how to use these utilities,
see Managing Exadata Databases Manually.
For administrators: The policy in Let database admins manage DB systems lets the specified
group do everything with databases and related Database resources.
If you are new to policies, see Getting Started with Policies and Common Policies. If you want
more information about writing policies for databases, see Details for the Database Service.
Note
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
A list of DB systems is displayed.
3. In the list of DB systems, find the Exadata DB system in which you want to create the
database, and then click its name to display details about it.
4. Click Create Database.
5. In the Create Database dialog, enter the following:
l Database name: The name for the database. The database name must begin
with an alphabetic character and can contain a maximum of eight alphanumeric
characters. Special characters are not permitted.
l Database version: The version of the database. You can mix database versions
on the Exadata DB system.
l PDB name: (Optional) For version 12.1.0.2 and later, you can specify the name
of the pluggable database. The PDB name must begin with an alphabetic
character, and can contain a maximum of 8 alphanumeric characters. The only
special character permitted is the underscore ( _).
l Database Home: The Oracle Database Home for the database. Choose the
applicable option:
o Select an existing Database Home: The Database Home display name
field allows you to choose the Database Home from the existing homes for
the database version you specified. If no Database Home with that version
exists, you must create a new one.
o Create a new Database Home: A database home will be created using
the database version and the Database Home display name you specified.
l Create administrator credentials: A database administrator SYS user will be
created with the password you supply.
o Username: SYS
o Password: Supply the password for this user. The password must meet the
following criteria:
A strong password for SYS, SYSTEM, TDE wallet, and PDB Admin. The
password must be 9 to 30 characters and contain at least two uppercase,
two lowercase, two numeric, and two special characters. The special
characters must be _, #, or -. The password must not contain the username
(SYS, SYSTEM, and so on) or the word "oracle" either in forward or
reversed order and regardless of casing.
o Confirm password: Re-enter the SYS password you specified.
l Select workload type: Choose the workload type that best suits your
application:
When the database creation is complete, the status changes from Provisioning to Available.
l When you create a database from a backup, the availability domain is the same as the
availability domain that hosts the backup.
l The Oracle database software version you specify must be the same or later version as
that of the backed-up database.
l If you are creating a database from an automatic backup, then you can choose any level
0 weekly backup, or a level 1 incremental backup created after the most recent level 0
backup. For more information on automatic backups, see Automatic Incremental
Backups
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose a compartment from the Compartment drop-down list to display a list of DB
systems.
3. Click the name of a DB system in which you want to create a database, to display details
of the DB system and a list of existing databases.
4. Click the name of a database from which you want to create a database, to display
details of the database and a list of backups.
5. Choose a backup that you want to use to create a database.
You can either select a backup from the database details page, or select a backup from
the list of standalone backups for your compartment.
also access the list of backups for a database by clicking Backups in the
Resources section.
6. Click the Actions icon (three dots) for the backup you chose.
7. Click Create Database.
8. On the Create Database from Backup page:
In the Configure your DB system section:
l Choose a shape from the Select a shape drop-down list.
l Choose a DB system from the Select a DB System drop-down list.
l In the Configure Database Home section, select either Select an existing
Database Home or Create a new Database home.
Choose a database home from the Select a Database Home drop-down list.
In the Configure database section:
l In the Database name field, accept the default name or name the database.
The database name must begin with an alphabetic character and can contain a
maximum of eight alphanumeric characters. Special characters are not
permitted.
l In the Password and Confirm password fields, enter and re-enter a password.
A strong password for SYS administrator must be 9 to 30 characters and contain
at least two uppercase, two lowercase, two numeric, and two special characters.
The special characters must be _, #, or -. The password must not contain the user
name (SYS, SYSTEM, and so on) or the word "oracle" either in forward or reverse
order and regardless of casing.
In the Enter the source database's TDE wallet or RMAN password field, enter a
password that matches either the Transparent Data Encryption (TDE) wallet password
or RMAN password for the source database.
9. Click Create Database.
To terminate a database
You'll get the chance to back up the database prior to terminating it. This creates a standalone
backup that can be used to create a database later. We recommend that you create this final
Note
You cannot terminate a database that is assuming the primary role in a Data Guard
association. To terminate it, you can switch it over to the standby role.
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
A list of DB systems is displayed.
3. In the list of DB systems, find the DB system that contains the database you want to
terminate, and then click its name to display details about it.
4. In the list of databases, find the database you want to terminate, and then click its
name to display details about it.
5. Click Actions, and then click Terminate.
6. In the confirmation dialog, indicate whether you want to back up the database before
terminating it, and type the name of the database to confirm the termination.
7. Click Terminate Database.
The database's status indicates Terminating.
l ListDatabases
l GetDatabase
l CreateDatabase
l UpdateDatabase - Use this operation to move a database to another Database Home
l DeleteDatabase
For the complete list of APIs for the Database service, see Database Service API.
Note that if you are enabling Data Guard for a database, the SYS password and the TDE wallet
password of the primary and standby databases must all be the same.
l dbaasapi - For adding and removing databases from the Exadata DB system. See Using
dbaasapi.
l dbaascli - For a variety of life-cycle and administration operations such as:
o Starting and stoping a database
o Starting and stoping the Oracle Net listener
o Viewing information about Oracle Homes
o Moving a database to another Oracle Home
o Deleting an unused Oracle Home
o Performing database configuration changes
o Managing Oracle Database software images
o Managing pluggable databases (PDBs)
o Performing database recovery
o Rotating the master encryption key
For details about how to use this CLI, see The dbaascli Utility.
Using dbaasapi
You can use the dbaasapi command line utility to create and delete databases on an Exadata
DB system. The utility operates like a REST API. It reads a JSON request body and produces a
JSON response body in an output file.
The utility is located in the /var/opt/oracle/dbaasapi/ directory on the compute nodes and
must be run as the root user.
To learn how to add or remove Exadata databases by using the Oracle Cloud Infrastructure
Console or API instead, see Managing Oracle Exadata Databases.
Note
Prerequisites
If you plan to create a database and store its backups in the Oracle Cloud Infrastructure
Object Storage, refer to the prerequisites in Managing Exadata Database Backups, and ensure
that the system meets the networking requirements for backing up to Object Storage. Review
the Create Database Parameters and gather the information you'll need to supply in the input
file you create for the dbaasapi operation.
Warning
Creating a Database
The following procedure creates directory called dbinput, a sample input file called
myinput.json, and a sample output file called createdb.out.
3. Make a directory for the input file and change to the directory.
[root@dbsys ~]# mkdir –p /home/oracle/dbinput
# cd /home/oracle/dbinput
4. Create the input file in the directory. The following sample file will create a database
configured to store backups in an existing bucket in Object Storage. For parameter
descriptions, see Create Database Parameters.
{
"object": "db",
"action": "start",
"operation": "createdb",
"params": {
"nodelist": "",
"dbname": "exadb",
"edition": "EE_EP",
"version": "12.1.0.2",
"ohome_name": "oradbhome1",
"adminPassword": "<password>",
"sid": "exadb",
"pdbName": "PDB1",
"charset": "AL32UTF8",
"ncharset": "AL16UTF16",
"backupDestination": "OSS",
"cloudStorageContainer": "https://swiftobjectstorage.<region_
name>.oraclecloud.com/v1/mycompany/DBBackups",
"cloudStorageUser": "<[email protected]>",
"cloudStoragePwd": "<auth_token>"
},
"outputfile": "/home/oracle/createdb.out",
"FLAGS": ""
}
7. Create a JSON file to check the database creation status. Note the action of "status".
Replace the ID and the dbname with the values from the previous steps.
{
"object": "db",
"action": "status",
"operation": "createdb",
"id": 170,
"params": {
"dbname": "exadb"
},
"outputfile": "/home/oracle/createdb.out",
"FLAGS": ""
}
8. Run the utility with the status file as input and then check the utility output.
Rerun the status action regularly until the response indicates that the operation
succeeded or failed.
[root@dbsys ~]# /var/opt/oracle/dbaasapi/dbaasapi -i db_status.json
{
"msg" : "Sync sqlnet file...[done]\\n##Done executing tde\\nWARN: Could not register elogger_
parameters: elogger.pm::_init: /var/opt/oracle/dbaas_acfs/events does not exist\\n##Invoking
assistant bkup\\nUsing cmd : /var/opt/oracle/ocde/assistants/bkup/bkup -out
/var/opt/oracle/ocde/res/bkup.out -sid=\"exadb1\" -reco_grp=\"RECOC1\" -
hostname=\"ed1db01.data.customer1.oraclevcn.com\" -oracle_
home=\"/u02/app/oracle/product/12.1.0/dbhome_5\" -dbname=\"exadb\" -dbtype=\"exarac\" -
exabm=\"yes\" -edition=\"enterprise\" -bkup_cfg_files=\"no\" -acfs_vol_
dir=\"/var/opt/oracle/dbaas_acfs\" -bkup_oss_url=\"bkup_oss_url\" -bkup_oss_user=\"bkup_oss_
user\" -version=\"12102\" -oracle_base=\"/u02/app/oracle\" -firstrun=\"no\" -action=\"config\" -
bkup_oss=\"no\" -bkup_disk=\"no\" -data_grp=\"DATAC1\" -action=config \\n\\n##Done executing
bkup\\nWARN: Could not register elogger_parameters: elogger.pm::_init: /var/opt/oracle/dbaas_
acfs/events does not existRemoved all entries from creg file : /var/opt/oracle/creg/exadb.ini
matching passwd or decrypt_key\\n\\n#### Completed OCDE Successfully ####\\nWARN: Could not
register elogger_parameters: elogger.pm::_init: /var/opt/oracle/dbaas_acfs/events does not
exist",
"object" : "db",
"status" : "Success",
"errmsg" : "",
"outputfile" : "/home/oracle/createdb_exadb.out",
"action" : "start",
"id" : "170",
"operation" : "createdb",
"logfile" : "/var/opt/oracle/log/exadb/dbaasapi/db/createdb/170.log"
}
Parameter Description
nodelist The value "" (an empty string). The database will be created
across all nodes in the cluster.
Note
ohome_name The name of the Oracle Database Home to use for the new
database, in quotes.
Parameter Description
adminPassword The administrator (SYS and SYSTEM) password to use for the
new database, in quotes. The password must be nine to thirty
characters and contain at least two uppercase, two lowercase,
two numeric, and two special characters. The special characters
must be _, #, or -.
Parameter Description
Allowed values
AL32UTF8, AR8ADOS710, AR8ADOS720, AR8APTEC715,
AR8ARABICMACS, AR8ASMO8X, AR8ISO8859P6, AR8MSWIN1256,
AR8MUSSAD768, AR8NAFITHA711, AR8NAFITHA721,
AR8SAKHR706, AR8SAKHR707, AZ8ISO8859P9E, BG8MSWIN,
BG8PC437S, BLT8CP921, BLT8ISO8859P13, BLT8MSWIN1257,
BLT8PC775, BN8BSCII, CDN8PC863, CEL8ISO8859P14,
CL8ISO8859P5, CL8ISOIR111, CL8KOI8R, CL8KOI8U,
CL8MACCYRILLICS, CL8MSWIN1251, EE8ISO8859P2,
EE8MACCES, EE8MACCROATIANS, EE8MSWIN1250, EE8PC852,
EL8DEC, EL8ISO8859P7, EL8MACGREEKS, EL8MSWIN1253,
EL8PC437S, EL8PC851, EL8PC869, ET8MSWIN923, HU8ABMOD,
HU8CWI2, IN8ISCII, IS8PC861, IW8ISO8859P8,
IW8MACHEBREWS, IW8MSWIN1255, IW8PC1507, JA16EUC,
JA16EUCTILDE, JA16SJIS, JA16SJISTILDE, JA16VMS,
KO16KSCCS, KO16MSWIN949, LA8ISO6937, LA8PASSPORT,
LT8MSWIN921, LT8PC772, LT8PC774, LV8PC1117, LV8PC8LR,
LV8RST104090, N8PC865, NE8ISO8859P10, NEE8ISO8859P4,
RU8BESTA, RU8PC855, RU8PC866, SE8ISO8859P3,
TH8MACTHAIS, TH8TISASCII, TR8DEC, TR8MACTURKISHS,
TR8MSWIN1254, TR8PC857, US7ASCII, US8PC437, UTF8,
VN8MSWIN1258, VN8VN3, WE8DEC, WE8DG, WE8ISO8859P15,
WE8ISO8859P9, WE8MACROMAN8S, WE8MSWIN1252, WE8NCR4970,
WE8NEXTSTEP, WE8PC850, WE8PC858, WE8PC860, WE8ROMAN8,
ZHS16CGB231280, ZHS16GBK, ZHT16BIG5, ZHT16CCDC,
ZHT16DBT, ZHT16HKSCS, ZHT16MSWIN950, ZHT32EUC,
ZHT32SOPS, ZHT32TRIS
Parameter Description
For example:
"backupDestination":"BOTH"
Parameter Description
https://swiftobjectstorage.<region_
name>.oraclecloud.com/v1/<tenant>/<bucket>
For example:
"cloudStorageContainer":"https://
swiftobjectstorage.<region_
name>.oraclecloud.com/v1/<company_name>/DBBackups"
"cloudStorageUser":"[email protected]"
This is the user name you use to sign in to the Console. The user
name must be a member of the Administrators group, as
described in Prerequisites.
Parameter Description
"cloudStoragePwd":"<auth_token>"
outputfile The absolute path for the output of the request, for example,
"outputfile":"/home/oracle/createdb.out".
Deleting a Database
We recommend that you create a final backup before you delete any production (non-test)
database. See Managing Exadata Database Backups by Using bkup_api to learn how to back
up an Exadata database.
3. Make a directory for the input file and change to the directory.
[root@dbsys ~]# mkdir –p /home/oracle/dbinput
# cd /home/oracle/dbinput
4. Create the input file in the directory and specify the database name to delete and an
output file. For more information, see Delete Database Parameters .
{
"object": "db",
"action": "start",
"operation": "deletedb",
"params": {
"dbname": "exadb"
},
"outputfile": "/home/oracle/delete_exadb.out",
"FLAGS": ""
}
{
"msg" : "",
"object" : "db",
"status" : "Starting",
"errmsg" : "",
"outputfile" : "/home/oracle/deletedb.out",
"action" : "start",
"id" : "17",
"operation" : "deletedb",
"logfile" : "/var/opt/oracle/log/exadb/dbaasapi/db/deletedb/17.log"
}
7. Create a JSON file to check the database deletion status. Note the action of "status" in
the sample file below. Replace the ID and the dbname with the values from the previous
steps.
{
"object": "db",
"action": "status",
"operation": "deletedb",
"id": 17,
"params": {
"dbname": "exadb"
},
"outputfile": "/home/oracle/deletedb.out",
"FLAGS": ""
}
8. Run the utility with the status file as input and then check the utility output.
Rerun the status action regularly until the response indicates that the operation
succeeded.
[root@dbsys ~]# /var/opt/oracle/dbaasapi/dbaasapi -i db_status.json
{
"msg" : "Using cmd : su - root -c \"/var/opt/oracle/ocde/assistants/dg/dgcc -dbname exadb -
action delete\" \\n\\n##Done executing dg\\nWARN: Could not register elogger_parameters:
elogger.pm::_init: /var/opt/oracle/dbaas_acfs/events does not exist\\n##Invoking assistant
bkup\\nUsing cmd : /var/opt/oracle/ocde/assistants/bkup/bkup -out
/var/opt/oracle/ocde/res/bkup.out -bkup_oss_url=\"bkup_oss_url\" -bkup_daily_time=\"0:13\" -bkup_
oss_user=\"bkup_oss_user\" -dbname=\"exadb\" -dbtype=\"exarac\" -exabm=\"yes\" -firstrun=\"no\" -
action=\"delete\" -bkup_cfg_files=\"no\" -bkup_oss=\"no\" -bkup_disk=\"no\" -action=delete
\\n\\n##Done executing bkup\\nWARN: Could not register elogger_parameters: elogger.pm::_init:
/var/opt/oracle/dbaas_acfs/events does not exist\\n##Invoking assistant dbda\\nUsing cmd :
/var/opt/oracle/ocde/assistants/dbda/dbda -out /var/opt/oracle/ocde/res/dbda.out -em=\"no\" -pga_
target=\"2000\" -dbtype=\"exarac\" -sga_target=\"2800\" -action=\"delete\" -build=\"no\" -
nid=\"no\" -dbname=\"exadb\" -action=delete \\n",
"object" : "db",
"status" : "InProgress",
"errmsg" : "",
"outputfile" : "/home/oracle/deletedb.out",
"action" : "start",
"id" : "17",
"operation" : "deletedb",
"logfile" : "/var/opt/oracle/log/exadb/dbaasapi/db/deletedb/17.log"
}
Parameter Description
outputfile The absolute path for the output of the request, for example,
"/home/oracle/deletedb.out".
Important
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.
If you're new to policies, see Getting Started with Policies and Common Policies.
Prerequisites
l Review the information and instructions in Configuring a Static Route for Accessing the
Object Store and ensure that you configure the static route for the backup subnet on
each compute node in the Exadata DB system.
l Your DB system must have connectivity to the applicable Swift endpoint for Object
Storage. See https://www.oracle.com/cloud/storage/object-storage-faq.html for
information about the Swift endpoints to use.
Important
You can use the Console to enable automatic incremental backups, create full backups on
demand, and view the list of managed backups for a database. The Console also allows you to
delete full backups.
Note
The database and DB system must be in an “Available” state for a backup operation to run
successfully. Oracle recommends that you avoid performing actions that could interfere with
availability (such as patching operations) while a backup operation is in progress. If an
automatic backup operation fails, the Database service retries the operation during the next
day’s backup window. If an on-demand full backup fails, you can try the operation again when
the DB system and database availability are restored.
When you enable the Automatic Backup feature, the service creates daily incremental
backups of the database to Object Storage. The first backup created is a level 0 backup. Then,
level 1 backups are created every day until the next weekend. Every weekend, the cycle
repeats, starting with a new level 0 backup.
BACKUP RETENTION
If you choose to enable automatic backups, you can choose one of the following preset
retention periods: 7 days, 15 days, 30 days, 45 days, or 60 days. The system automatically
deletes your incremental backups at the end of your chosen retention period.
BACKUP SCHEDULING
The automatic backup process starts at any time during your daily backup window. You can
optionally specify a 2-hour scheduling window for your database during which the automatic
backup process will begin. There are 12 scheduling windows to choose from, each starting on
an even-numbered hour (for example, one window runs from 4:00-6:00 AM, and the next
from 6:00-8:00 AM). Backups jobs do not necessarily complete within the scheduling window
The default backup window of 00:00 to 06:00 in the time zone of the DB system's region is
assigned to your database if you do not specify a window. Note that the default backup
scheduling window is six hours long, while the windows you specify are two hours long.
Note
S TANDALONE BACKUPS
When you terminate a DB system or a database, all of its resources are deleted, along with
any automatic backups. Full backups remain in Object Storage as standalone backups. You
can use a standalone backup to create a new database.
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
A list of DB systems is displayed.
3. Find the DB system where the database is located, and click the system name to display
details about it.
A list of databases is displayed.
4. Find the database for which you want to enable or disable automatic backups, and click
its name to display database details. The details indicate whether automatic backups
are enabled.
5. Click Configure Automatic Backups.
6. In the Configure Automatic Backups dialog, check or uncheck Enable Automatic
Backup, as applicable. If you are enabling automatic backups, you can choose one of
the following preset retention periods: 7 days, 15 days, 30 days, 45 days, or 60 days.
The default selection is 30 days.
7. Click Save Changes.
4. Find the database for which you want to create an on-demand full backup and click its
name to display database details.
5. Under Resources, click Backups.
A list of backups is displayed.
6. Click Create Backup.
Note
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
A list of DB systems is displayed.
3. Find the DB system where the database is located and click the DB system name to
display details.
A list of databases is displayed.
4. Find the database you are interested in and click its name to display database details.
5. Under Resources, click Backups.
A list of backups is displayed.
6. Click the Actions icon (three dots) for the backup you are interested in, and then click
Delete.
7. Confirm when prompted.
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.
l ListBackups
l GetBackup
l CreateBackup
l DeleteBackup
l UpdateDatabase - To enable and disable automatic backups.
For the complete list of APIs for the Database service, see Database Service API.
WH AT'S NEXT?
For backups managed by Oracle Cloud Infrastructure, see Managing Exadata Database
Backups.
l Create a backup configuration file that indicates the backup destination, when the
backup should run, and how long backups are retained. If the backup destination is
Object Storage, the file also contains the credentials to access the service.
l Associate the backup configuration file with a database. The database will be backed up
as scheduled, or you can create an on-demand backup.
Note
Prerequisites
l The Exadata DB system requires access to the Oracle Cloud Infrastructure Object
Storage service. Oracle recommends using a service gateway with the VCN to enable
this access. For more information, see Network Setup for Exadata DB Systems. In that
topic, pay particular attention to:
o Service Gateway for the VCN
o Node Access to Object Storage: Static Route
o Rule Required Specifically for the Backup Network
l An existing Object Storage bucket to use as the backup destination. You can use the
Console or the Object Storage API to create the bucket. For more information, see
Managing Buckets.
l An auth token generated by Oracle Cloud Infrastructure. You can use the Console or the
IAM API to generate the password. For more information, see Working with Auth
Tokens.
l The user name specified in the backup configuration file must have tenancy-level access
to Object Storage. An easy way to do this is to add the user name to the Administrators
group. However, that allows access to all of the cloud services. Instead, an
administrator should create a policy like the following that limits access to only the
required resources in Object Storage for backing up and restoring the database:
Allow group <group_name> to manage objects in compartment <compartment_name> where
target.bucket.name = '<bucket_name>'
For more information about adding a user to a group, see Managing Groups. For more
information about policies, see Getting Started with Policies.
l Full (level 0) backup of the database followed by rolling incremental (level 1) backups
on a seven-day cycle (a 30-day cycle for the Object Storage destination).
l Full backup of selected system files.
l Automatic backups daily at a specific time set during the database deployment creation
process.
Retention period:
l Both Object Storage and local storage: 30 days, with the 7 most recent days' backups
available on local storage.
l Object Storage only: 30 days.
l Local storage only: Seven days.
Encryption:
l Both Object Storage and local storage: All backups to cloud storage are encrypted.
l Object Storage only: All backups to cloud storage are encrypted.
Managing Backups
Important
$ $ORACLE_HOME/bin/olsnodes -n
The first node has the number 1 listed beside the node
name.
vi bkup.cfg
bkup_disk=yes
bkup_oss=yes
bkup_oss_url=https://swiftobjectstorage.<region>.oraclecloud.com/v1/companyabc/DBBackups
bkup_oss_user=<oci_user_name>
bkup_oss_passwd=<password>
bkup_oss_recovery_window=7
bkup_daily_time=06:45
5. Use the following command to install the backup configuration, configure the
credentials, schedule the backup, and associate the configuration with a database
name.
[root@dbsys bkup]# ./bkup -cfg bkup.cfg -dbname=<database_name>
When the scheduled backup runs, you can check its progress with the following command.
[root@dbsys bkup]# /var/opt/oracle/bkup_api/bkup_api bkup_status
The backup configuration file parameters are described in the following table:
Parameter Description
Parameter Description
https://
swiftobjectstorage
.<region_
name>
.
oraclecloud
.
com
/v1/<tenant>/<bucket>
Parameter Description
For example,
[email protected] for a
local user or <identity_
provider>
/[email protected] for
a federated user.
Parameter Description
To determine the first compute node, connect to any compute node as the grid user and
execute the following command:
$ $ORACLE_HOME/bin/olsnodes -n
The first node has the number 1 listed beside the node name.
2. Log in as opc and then sudo to the root user.
login as: opc
3. You can let the backup follow the current retention policy, or you can create a long-term
backup that persists until you delete it:
l To create a backup that follows the current retention policy, enter the following
command:
# /var/opt/oracle/bkup_api/bkup_api bkup_start --dbname=<database_name>
4. Exit the root-user command shell and disconnect from the compute node:
# exit
$ exit
By default, the backup is given a timestamp-based tag. To specify a custom backup tag, add
the --tag option to the bkup_api command; for example, to create a long-term backup with
the tag "monthly", enter the following command:
# /var/opt/oracle/bkup_api/bkup_api bkup_start --keep --tag=monthly
After you enter a bkup_api bkup_start command, the bkup_api utility starts the backup
process, which runs in the background. To check the progress of the backup process, enter the
following command:
# /var/opt/oracle/bkup_api/bkup_api bkup_status --dbname=<database_name>
1. Connect to the first compute node in your Exadata DB system as the opc user.
To determine the first compute node, connect to any compute node as the grid user and
execute the following command:
$ $ORACLE_HOME/bin/olsnodes -n
The first node has the number 1 listed beside the node name.
2. Start a root-user command shell:
$ sudo -s#
where dbname is the database name for the database that you want to act on.
A list of available backups is displayed.
4. Delete the backup you want:
# /var/opt/oracle/bkup_api/bkup_api bkup_delete --bkup=<backup-tag> --dbname=<database_name>
WHAT NEXT?
If you used Object Storage as a backup destination, you can display the backup files in your
bucket in the Console on the Storage page, by selecting Object Storage.
You can manually restore a database backup by using the RMAN utility. For information about
using RMAN, see the Oracle Database Backup and Recovery User's Guide for Release 18.1,
12.2, 12.1, or 11.2.
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.
If you're new to policies, see Getting Started with Policies and Common Policies.
You can use the Console to restore the database from a backup in the Object Storage that was
created by using the Console or the API. You can restore to the last known good state of the
database, or you can specify a point in time or an existing System Change Number (SCN).
Note
To restore a database
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
A list of DB systems is displayed.
3. Find the DB system where the database is located, and click the system name to display
details about it.
A list of databases is displayed.
4. Find the database you want to restore, and click its name to display details about it.
5. Click Restore.
6. Select one of the following options, and click Restore Database:
l Restore to the latest: Restores the database to the last known good state with
the least possible data loss.
l Restore to the timestamp: Restores the database to the timestamp specified.
l Restore to System Change Number (SCN): Restores the database using the
SCN specified. This SCN must be valid.
Tip
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.
l ListBackups
l GetBackup
l RestoreDatabase
For the complete list of APIs for the Database service, see Database Service API.
A Database Home is a directory location on the Exadata database compute nodes that contains
Oracle Database software binary files.
When you create an Exadata DB system, an initial Database Home is created in that system
and an initial database is created in that Database Home. After you provision the system, you
can create additional Database Homes in the DB system, and add databases to any of the
Database Homes.
Warning
You can also add and remove Database Homes, and perform other management tasks on a
Database Home by using the dbaascli utility. For information and instructions, see Managing
Oracle Database Homes Manually.
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: The policy in Let database admins manage DB systems lets the specified
group do everything with databases and related Database resources.
If you're new to policies, see Getting Started with Policies and Common Policies. If you want
to dig deeper into writing policies for databases, see Details for the Database Service.
3. In the list of DB systems, find the Exadata DB system on which you want to create the
Database Home, and then click its name to display details about it.
4. Under Resources, click Database Homes.
A list of Database Homes is displayed.
5. Click Create Database Home.
6. In the Create Database Home dialog, enter the following:
l Database Home display name: The display name for the Database Home.
l Database version: The Oracle Database version for this Database Home. Your
Database Homes can have different database versions on the Exadata DB system.
l Click Show Advanced Options to specify advanced options for the Database
Home.
o Tags: Optionally, you can apply 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.
When the Database Home creation is complete, the status changes from Provisioning to
Available.
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.
For the complete list of APIs for the Database service, see Database Service API.
For information on how to perform these tasks manually, see Managing Oracle Database
Homes Manually.
Warning
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: The policy in Let database admins manage DB systems lets the specified
group do everything with databases and related Database resources.
If you're new to policies, see Getting Started with Policies and Common Policies. If you want
to dig deeper into writing policies for databases, see Details for the Database Service.
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
3. In the list of DB systems, find the Exadata DB system that contains the Database Home
you want to delete, and then click its name to display details about it.
4. On the DB System Details page, under Resources, click Database Homes.
5. In the list of Database Homes, find the Database Home you want to delete, and then
click its name to display details about it.
6. On the Database Home Details page, click Delete.
If the Database Home contains databases, you will not be able to proceed. You must
cancel the deletion, empty the Database Home as applicable, and then retry the
deletion.
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.
l ListDbHomes
l GetDbHome
l DeleteDbHome
For the complete list of APIs for the Database service, see Database Service API.
An Oracle Database Home is a directory location on the compute nodes that contains Oracle
Database binaries. Exadata DB systems enable multiple databases to share a set of Oracle
Database binaries in a shared Oracle Home directory location.
For information on how to manage Database Homes by using the Oracle Cloud Infrastructure
Console, the API, or the CLI, see Managing Oracle Database Homes on Exadata DB Systems.
You can view information about Oracle Home directory locations by using the dbhome info
subcommand of the dbaascli utility as follows.
4. When prompted, press Enter to view information about all Oracle Homes registered in
your Exadata DB system, or specify an Oracle Home name to view information only
about that Oracle Home.
5. Exit the root-user command shell:
# exit
$
Moving a database to another Oracle Home enables you to consolidate existing Oracle Homes
and manage the storage that they consume. You can move a database to another Oracle
Home by using the database move subcommand of the dbaascli utility as follows.
3. Ensure that all database instances associated with the database deployment are up and
running.
# dbaascli database status --dbname <dbname>
In the preceding command, <dbname> specifies the name of the database that you
want to check.
Restart any database instances that are not running and open.
4. Execute the dbaascli command with the database move subcommand:
# dbaascli database move --dbname <dbname> --ohome <oracle_home>
You can create an Oracle Home directory location and software installation, without creating a
database, by using the dbhome create subcommand of the dbaascli utility as follows.
If an Oracle Home directory does not support any databases, you can delete it by using the
dbhome purge subcommand of the dbaascli utility as follows.
See the command reference list in this topic to learn what commands are available.
You need a username and password to connect to the Exadata Storage Server. On Exadata
Cloud@Customer, the preconfigured user is cloud_user_clustername, where clustername
is the name of the virtual machine (VM) cluster that is being used. You can determine the
name of the VM cluster by running the following command as the grid user on any cluster
node:
$ crsctl get cluster name
Command Syntax
For Exadata Storage Server targets, ExaCLI supports the same command syntax as CellCLI.
Construct you commands using the syntax that follows. Note that the syntax example
assumes you are the opc user on a compute node.
exacli -c [username@]remotehost[:port] [-l username] [--xml] [--cookie-jar filename] [-e {command |
'command; command' | @batchfile}]
EXAMPLE 1
This example shows the user on an Exadata compute node issuing the command to log in to
ExaCLI start an interactive ExaCLI session on a storage server:
[opc@exacs-node1 ~]$ exacli -l cloud_user_clustername -c 192.168.136.7
See Finding the IP addresses of storage cells using the cellip.ora file for information on
determining your storage server's IP address.
EXAMPLE 2
This example shows a single command issued on a compute node that does the following:
Options
Option Description
--connect
[username@]remotehost
[:port]
-l username or Specifies the user name to log into the remote node. The
preconfigured user is cloud_user_clustername.
--login-name username
--cookie-jar Specifies the filename of the cookie jar to use. If filename is not
[filename] specified, the cookie is stored in a default cookie jar located at
HOME/.exacli/cookiejar, where HOME is the home directory
of the OS user running the ExaCLI command.
Option Description
--no-prompt
Usage Notes
To use ExaCLI on storage servers, you will need to know your target storage server's
IP address. If you do not know the IP address of the node you want to connect to, you can find
it by viewing the contents of the cellip.ora file.
The following example illustrates how to do so on the UNIX command line for a quarter rack
system. (Note that a quarter rack has three storage cells, and each cell has two connections,
so a total of six IP addresses are shown.)
[root@exacs-node1 ~]# cat /etc/oracle/cell/
network-config/cellip.ora
cell="192.168.136.5;cell="192.168.136.6"
cell="192.168.136.7;cell="192.168.136.8"
cell="192.168.136.9;cell="192.168.136.10"
If you are connecting to a storage cell for the first time using ExaCLI, you may be prompted to
accept an SSL certificate. The ExaCLI output in this case will look like the following:
[opc@exacs-node1 ~]$ exacli -l cloud_user_clustername -c 192.168.136.7 --cookie-jar
No cookies found for [email protected]
Password: *********
EXA-30016: This connection is not secure. You have asked ExaCLI to connect to cell 192.168.136.7
securely. The identity of 192.168.136.7 cannot be verified.
Got certificate from server:
C=US,ST=California,L=Redwood City,O=Oracle Corporation,OU=Oracle Exadata,CN=ed1cl03clu01-
priv2.usdc2.oraclecloud.com
Do you want to accept and store this certificate? (Press y/n)
Accept the self-signed Oracle certificate by pressing "y" to continue using ExaCLI.
You can execute various ExaCLI commands to monitor and manage Exadata Storage Servers
associated with your Oracle Cloud Infrastructure Exadata DB system. ExaCLI allows you to get
up-to-date, real-time information about your Exadata Cloud Service.
l ACTIVEREQUEST- Lists all active requests that are currently being served by the
storage servers.
l ALERTDEFINITION - Lists all possible alerts and their sources for storage servers.
l ALERTHISTORY - Lists all alerts that have been issues for the storage servers.
l CELL - Used to list the details of a specific attribute of the storage servers or storage
cells. The syntax is as follows: LIST CELL ATTRIBUTES A,B,C, with A, B, and C being
attributes. To see all cell attributes, use the LIST CELL ATTRIBUTES ALL command.
l CELLDISK - Lists the attributes of the cell disks in the storage servers. Use the
following syntax to list the cell disk details: LIST CELLDISK cell_disk_name DETAIL.
l DATABASE - Lists details of the databases. Uses the regular LIST command syntax:
LIST DATABASE and LIST DATABASE DETAIL. You can also use this command to show
an individual attribute with the following syntax: LIST DATABASE ATTRIBUTES NAME.
l FLASHCACHE - Lists the details of the Exadata system's flash cache. For this object,
you can use the following syntax patterns: LIST FLASHCACHE DETAIL or LIST
FLASHCACHE ATTRIBUTES attribute_name.
l FLASHCACHECONTENT - Lists the details of all objects in the flash cache, or the
details of a specified object ID. To list all the details of all objects, use LIST
FLASHCACHECONTENT DETAIL. To list details for a specific object, use a where clause as
follows: LIST FLASHCACHECONTENT WHERE objectNumber=12345 DETAIL
Note: To find the object ID of a specific object, you can query user_objects using the
object's name to get the data_object_id of a partition or table.
l FLASHLOG - Lists the attributes for the Oracle Exadata Smart Flash Log.
l GRIDDISK - Lists the details of a particular grid disk. The syntax is similar to the
CELLDISK command syntax. To view all attributes: LIST GRIDDISK grid_disk_name
DETAIL. To view specified attributes of the grid disk: LIST GRIDDISK grid_disk_name
ATTRIBUTES size, name.
l IBPORT - Lists details of the InfiniBand ports. Syntax is LIST IBPORT DETAIL.
l IORMPROFILE - Lists any IORM profiles that have been set on the storage servers. You
can also refer back to the profile attribute on the DATABASE object if a database has an
IORM profile on it. Syntax is LIST IORMPROFILE.
l LUN - The LUN (logical unit number) object returns the number and the detail of the
physical disks in the storage servers. List the LUNs of the disks with LIST LUN. List the
details of each LUN with LIST LUN lun_number DETAIL.
l METRICCURRRENT - Lists the current metrics for a particular object type. Syntax is
LIST METRICCURRENT WHERE objectType = 'CELLDISK'. This command also allows
for sorting and results limits as seen in the following example:
LIST METRICCURRENT attributes name, metricObjectName ORDER BY
metricObjectName asc, name desc LIMIT 5
l METRICDEFINITION - Lists metric definitions for the object that you can then get
details for. With the command LIST metricDefinition WHERE objectType=cell, you
can get all the metrics for that object type. You can then use the metric definition object
again to get details for one of those specific metrics just listed: LIST
metricDefinition WHERE name= IORM_MODE DETAIL.
l METRICHISTORY - List metrics over a specified period of time. For example, with the
command LIST METRICHISTORY WHERE ageInMinutes < 30, you can list all the
metrics collected over the past 30 minutes. You can also use the predicate
collectionTime to set a range from a specific time. Use collectionTime as shown in the
follow example: LIST METRICHISTORY WHERE collectionTime > '2018-04-
01T21:12:00-10:00'. The metric history object can also be used to see a specific
metric using the object’s name (for example, LIST METRICHISTORY CT_FD_IO_RQ_SM)
or with a "where" clause to get objects with similar attributes like name (for example,
LIST METRICHISTORY WHERE name like 'CT_.*').
l OFFLOADGROUP - Lists the attributes for the offload group that are running on your
storage servers. You can list all details for all groups with LIST OFFLOADGROUP DETAIL,
or list the attributes for a specific group, as shown in the following example: LIST
OFFLOADGROUP offloadgroup4. List specific attributes with LIST OFFLOADGROUP
ATTRIBUTES name.
l PHYSICALDISK - Lists all physical disks. Use the results of LIST PHYSICALDISK to
identify a specific disk for further investigation, then list the details of that disk using
the command as follows: LIST PHYSICALDISK 20:10 DETAIL. To list the details of
flash disks, use the command as follows: LIST PHYSICALDISK FLASH_1_0 DETAIL).
l PLUGGABLEDATABASE - Lists all PDBs. View the details of a specific PDB with LIST
PLUGGABLEDATABASE pdb_name.
l QUARANTINE - Lists all SQL statements that you prevented from using Smart Scans.
The syntax is LIST QUARANTINE DETAIL. You can also use a "where" clause on any of
the available attributes.
Use the ExaCLI CREATE, ALTER, DROP, and LIST commands to act on the following Exadata
Storage Server objects:
l DIAGPACK - Lists the diagnostic packages and their status in your Exadata system. The
syntax is LIST DIAGPACK [DETAIL], with DETAIL being an optional attribute. Use
CREATE DIAGPACK with the packStartTime attribute to gather logs and trace files into a
single compressed file for downloading, as in the following example: CREATE DIAGPACK
packStartTime=2019_12_15T00_00_00. You can also use the value "now" with
l IORMPLAN - You can List, create, alter, and drop IORM plans using ExaCLI. To see the
details of all IORM plans, use LIST IORMPLAN DETAIL. You can also use the command
to create and alter IORM plans, and to apply plans to storage servers.
Note
This topic explains how to use the Console or the API to manage Oracle Data Guard
associations in your Exadata DB system. When you use the Console or the API to enable
Oracle Data Guard for an Oracle Cloud Infrastructure Exadata DB system database:
To configure an Oracle Data Guard system between on-premises and Oracle Cloud
Infrastructure DB systems, or to configure your database with multiple standbys, you must
access the database host directly and set up Oracle Data Guard manually.
For complete information on Oracle Data Guard, see the Data Guard Concepts and
Administration documentation on the Oracle Document Portal.
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.
If you are new to policies, see Getting Started with Policies and Common Policies.
Prerequisites
An Exadata DB system Oracle Data Guard implementation requires two Exadata DB systems:
one containing the primary database and one containing the standby database. When you
enable Oracle Data Guard for an Exadata DB system database, the DB system with the
database to be used as the standby must already exist before you enable Oracle Data Guard.
NETWORK REQUIREMENTS
l If you want to configure Oracle Data Guard across regions, then you must configure
remote virtual cloud network (VCN) peering between the primary and standby
databases. See Remote VCN Peering (Across Regions).
l To set up Oracle Data Guard within a single region, both DB systems must use the same
VCN. When setting up Data Guard within the same region, Oracle recommends that the
DB system of the standby database be in a different availability domain from the
DB system of the primary database to improve availability and disaster recovery.
l Configure the ingress and egress security rules for the subnets of both DB systems in
the Oracle Data Guard association to enable TCP traffic to move between the applicable
ports. Ensure that the rules you create are stateful (the default).
For example, if the subnet of the primary DB System uses the source CIDR 10.0.0.0/24
and the subnet of the standby DB system uses the source CIDR 10.0.1.0/24, then create
rules as shown in the subsequent example.
Note
Stateless: No
Source: 10.0.1.0/24
IP Protocol: TCP
Source Port Range: All
Destination Port Range: 1521
Allows: TCP traffic for ports: 1521
Egress Rules:
Stateless: No
Destination: 10.0.1.0/24
IP Protocol: TCP
Source Port Range: All
Destination Port Range: 1521
Allows: TCP traffic for ports: 1521
Ingress Rules:
Stateless: No
Source: 10.0.0.0/24
IP Protocol: TCP
Source Port Range: All
Destination Port Range: 1521
Allows: TCP traffic for ports: 1521
Egress Rules:
Stateless: No
Destination: 10.0.0.0/24
IP Protocol: TCP
Source Port Range: All
Destination Port Range: 1521
Allows: TCP traffic for ports: 1521
For information about creating and editing rules, see Security Lists.
PASSWORD REQUIREMENTS
For Oracle Data Guard operations to work, the SYS password and the TDE wallet password of
the primary and standby databases must all be the same. If you change any one of these
passwords, then you must update the rest of the passwords to match. See Changing the
Database Passwords to learn how to change the SYS password or the TDE wallet password.
If you make any change to the TDE wallet (such as adding a master key for a new PDB or
changing the wallet password), then you must copy the wallet from the primary database to
the standby database so that Oracle Data Guard can continue to operate. For Oracle Database
versions prior to Oracle Database 12c release 2 (12.2), if you change the SYS password on
one of the peers, then you must manually sync the password file between the DB systems.
Oracle Data Guard ensures high availability, data protection, and disaster recovery for
enterprise data. The Oracle Cloud Infrastructure Database Data Guard implementation
requires two databases: one in a primary role and one in a standby role. The two databases
compose an Oracle Data Guard association. Most of your applications access the primary
database. The standby database is a transactionally consistent copy of the primary database.
Oracle Data Guard maintains the standby database by transmitting and applying redo data
from the primary database. If the primary database becomes unavailable, then you can use
Oracle Data Guard to switch or failover the standby database to the primary role.
S WITCHOVER
A switchover reverses the primary and standby database roles. Each database continues to
participate in the Oracle Data Guard association in its new role. A switchover ensures no data
loss. Performing planned maintenance on a DB system with an Oracle Data Guard association
is typically done by switching the primary database to the standby role, performing
maintenance on the standby database, and then switching the standby database back to the
primary role.
FAILOVER
A failover transitions the standby database into the primary role after the existing primary
database fails or becomes unreachable. A failover might result in some data loss when you
use Maximum Performance protection mode.
REINSTATE
Reinstates a database into the standby role in an Oracle Data Guard association. You can use
the reinstate command to return a failed database into service after correcting the cause of
failure.
Note
Use the Console to enable an Oracle Data Guard association between databases, change the
role of a database in an Oracle Data Guard association using either a switchover or a failover
operation, and reinstate a failed database.
When you enable Oracle Data Guard, a separate Oracle Data Guard association is created for
the primary and the standby database.
Note
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose the Compartment that contains the Exadata DB system with the database for
which you want to enable Oracle Data Guard.
3. Click the name of an Exadata DB system that contains a database you want to assume
the primary role.
4. On the DB System Details page, in the Databases section, click the name of the
database you want to make primary.
5. On the Database Details page, in the Resources section, click Data Guard
Associations.
6. In the Data Guard Associations section, click Enable Data Guard.
7. On the Enable Data Guard page, configure the Oracle Data Guard association.
l The settings in the Data Guard association details section are read only and
cannot be changed.
o Protection mode: The protection mode used for this Oracle Data Guard
association is set to Maximum Performance.
o Transport type: The redo transport type used for this Oracle Data Guard
association is set to Async (asynchronous).
l In the Select peer DB system section, provide the following information for the
standby database to obtain a list of available DB systems in which to locate the
standby database:
o Region: Select a region where you want to locate the standby database.
The region where the primary database is located is selected, by default.
You can choose to locate the standby database in a different region. The hint
text associated with this field tells you in which region the primary database
is located.
o Availability domain: Select an availability domain for the standby
database. The hint text associated with this field tells you in which
availability domain the primary database is located.
o Shape: Select the shape of the standby DB system. The shape must be an
Exadata DB system shape.
o Peer DB system: Select the DB system that contains the standby
database.
l In the Configure standby database section, enter the database administrator
password of the primary database in the Database password field. Use this
same database administrator password for the standby database.
Note
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose the Compartment that contains the Exadata DB system with the primary
database you want to switch over.
3. Click the DB system name, and then click the name of the primary database.
4. Under Resources, click Data Guard Associations.
5. For the Data Guard association on which you want to perform a switchover, click the
Actions icon (three dots), and then click Switchover.
6. In the Switchover Database dialog box, enter the database admin password, and
then click OK.
This database should now assume the role of the standby, and the standby should
assume the role of the primary in the Data Guard association.
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose the Compartment that contains the Exadata DB system with the primary
database's peer standby you want to fail over to.
3. Click the DB system name, and then click the name of the standby database.
4. Under Resources, click Data Guard Associations.
5. For the Data Guard association on which you want to perform a failover, click Failover.
6. In the Failover Database dialog box, enter the database admin password, and then
click OK.
This database should now assume the role of the primary, and the old primary's role
should display as Disabled Standby.
To reinstate a database
After you fail over a primary database to its standby, the standby assumes the primary role
and the old primary is identified as a disabled standby. After you correct the cause of failure,
you can reinstate the failed database as a functioning standby for the current primary by using
its Data Guard association.
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose the Compartment that contains the Exadata DB system with the failed
database you want to reinstate.
3. Click the DB system name, and then click the database name.
4. Under Resources, click Data Guard Associations.
5. For the Data Guard association on which you want to reinstate this database, click the
Actions icon (three dots), and then click Reinstate.
6. In the Reinstate Database dialog box, enter the database admin password, and then
click OK.
This database should now be reinstated as the standby in the Data Guard association.
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose the Compartment that contains the Exadata DB system that includes the
standby database you want to terminate.
3. Click the DB system name.
4. For the standby database you want to terminate, click the Actions icon (three dots), and
then click Terminate.
5. In the Terminate Database dialog box, enter the name of the database, and then click
OK.
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.
l CreateDataGuardAssociation
l GetDataGuardAssociation
l ListDataGuardAssociations
l SwitchoverDataGuardAssociation
l FailoverDataGuardAssociation
l ReinstateDataGuardAssociation
l DeleteDbHome - To terminate an Exadata DB system Data Guard association, you
delete the standby database.
For the complete list of APIs for the Database service, see Database Service API.
When you create an Exadata DB system that uses Oracle Database 12c or later, an Oracle
Multitenant environment is created.
To use Oracle Transparent Data Encryption (TDE) in a pluggable database (PDB), you must
create and activate a master encryption key for the PDB.
In a multitenant environment, each PDB has its own master encryption key which is stored in
a single keystore used by all containers.
You must export and import the master encryption key for any encrypted PDBs you plug into
your Exadata DB system CDB.
If your source PDB is encrypted, you must export the master encryption key and then import
it.
You can export and import all of the TDE master encryption keys that belong to the PDB by
exporting and importing the TDE master encryption keys from within a PDB. Export and
import of TDE master encryption keys support the PDB unplug and plug operations. During a
PDB unplug and plug, all of the TDE master encryption keys that belong to a PDB, as well as
the metadata, are involved.
See "Exporting and Importing TDE Master Encryption Keys for a PDB" in Oracle Database
Advanced Security Guide for Release 19, 18, 12.2 or 12.1.
See "ADMINISTER KEY MANAGEMENT" in Oracle Database SQL Language Reference for
Release 19, 18, 12.2 or 12.1.
To determine if you need to create and activate an encryption key for the PDB
1. Invoke SQL*Plus and log in to the database as the SYS user with SYSDBA privileges.
2. Set the container to the PDB:
SQL> ALTER SESSION SET CONTAINER = pdb;
If the STATUS column contains a value of OPEN_NO_MASTER_KEY, you need to create and
activate the master encryption key.
2. Create and activate a master encryption key in the PDB by executing the following
command:
SQL> ADMINISTER KEY MANAGEMENT SET KEY USING TAG 'tag' FORCE KEYSTORE IDENTIFIED BY keystore-
password WITH BACKUP USING 'backup_identifier';
Note
3. Query V$ENCRYPTION_WALLET again to verify that the STATUS column is set to OPEN:
SQL> SELECT wrl_parameter, status, wallet_type FROM v$encryption_wallet;
4. Query V$INSTANCE and take note of the value in the HOST_NAME column, which identifies
the database server that contains the newly updated keystore files:
SQL> SELECT host_name FROM v$instance;
5. Copy the updated keystore files to all of the other database servers.
To distribute the updated keystore, you must perform the following actions on each
database server that does not contain the updated keystore files:
a. Connect to the root container and query V$ENCRYPTION_WALLET. Take note of the
keystore location contained in the WRL_PARAMETER column:
SQL> SELECT wrl_parameter, status FROM v$encryption_wallet;
Note
6. Query GV$ENCRYPTION_WALLET to verify that the STATUS column is set to OPEN across all
of the database instances:
SQL> SELECT wrl_parameter, status, wallet_type FROM gv$encryption_wallet;
SQL> ADMINISTER KEY MANAGEMENT EXPORT ENCRYPTION KEYS WITH SECRET "secret" TO 'filename'
IDENTIFIED BY keystore-password;
By default, all new tablespaces that you create in an Exadata database are encrypted.
However, the tablespaces that are initially created when the database is created may not be
encrypted by default.
l For databases that use Oracle Database 12c Release 2 or later, only the USERS
tablespaces initially created when the database was created are encrypted. No other
tablespaces are encrypted including the non-USERS tablespaces in:
o The root container (CDB$ROOT).
o The seed pluggable database (PDB$SEED).
o The first PDB, which is created when the database is created.
l For databases that use Oracle Database 12c Release 1 or Oracle Database 11g, none of
the tablespaces initially created when the database was created are encrypted.
For further information about the implementation of tablespace encryption in Exadata, along
with how it impacts various deployment scenarios, see Oracle Database Tablespace
Encryption Behavior in Oracle Cloud.
By default, any new tablespaces created by using the SQL CREATE TABLESPACE command are
encrypted with the AES128 encryption algorithm. You do not need to include the USING
'encrypt_algorithm' clause to use the default encryption.
You can specify another supported algorithm by including the USING 'encrypt_algorithm'
clause in the CREATE TABLESPACE command. Supported algorithms are AES256, AES192,
AES128, and 3DES168.
You can manage the software keystore (known as an Oracle wallet in Oracle Database 11g),
the master encryption key, and control whether encryption is enabled by default.
You can change (rotate) the master encryption key by using the ADMINISTER KEY MANAGEMENT
SQL statement. For example:
SQL> ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY USING TAG 'tag'
IDENTIFIED BY password WITH BACKUP USING 'backup';
keystore altered.
See "Managing the TDE Master Encryption Key" in Oracle Database Advanced Security Guide
for Release 19, 18, 12.2 or 12.1 or "Setting and Resetting the Master Encryption Key" in Oracle
Database Advanced Security Administrator's Guide for Release 11.2.
Value Description
ALWAYS During creation, tablespaces are transparently encrypted with the AES128
algorithm unless a different algorithm is specified in the ENCRYPTION clause.
CLOUD_ Tablespaces created in an Exadata database are transparently encrypted with the
ONLY AES128 algorithm unless a different algorithm is specified in the ENCRYPTION
clause. For non-cloud databases, tablespaces are only encrypted if the
ENCRYPTION clause is specified. ENCRYPTION is the default value.
DDL During creation, tablespaces are not transparently encrypted by default, and are
only encrypted if the ENCRYPTION clause is specified.
Note
Huge Pages provide considerable performance benefits for Oracle Database on systems with
large amounts of memory. Oracle Database on an Exadata DB system hosted in Oracle Cloud
Infrastructure provides configuration settings that make use of Huge Pages by default;
however, you can make manual adjustments to optimize the configuration of Huge Pages.
Huge Pages is a feature integrated into the Linux kernel 2.6. Enabling Huge Pages makes it
possible for the operating system to support large memory pages. Using Huge Pages can
improve system performance by reducing the amount of system CPU and memory resources
required to manage Linux page tables, which store the mapping between virtual and physical
memory addresses. For Oracle Databases, using Huge Pages can drastically reduce the
number of page table entries associated with the System Global Area (SGA).
On Exadata DB systems hosted in Oracle Cloud Infrastructure, a standard page is 4 KB, while
a Huge Page is 2 MB by default. Therefore, an Oracle Database on an Exadata DB system with
a 50 GB SGA requires 13,107,200 standard pages to house the SGA, compared with only
25,600 Huge Pages. The result is much smaller page tables, which require less memory to
store and fewer CPU resources to access and manage.
l At the operating system level, the overall amount of memory allocated to Huge Pages is
controlled by the vm.nr_hugepages entry in the /etc/sysctl.conf file. This setting is
made on each compute node in the environment and it is strongly recommended that
the setting is consistent across all of the compute nodes. To alter the Huge Page
allocation, you can execute the following command on each compute node as the root
user:
# sysctl -w vm.nr_hugepages=value
where value is the number of Huge Pages that you want to allocate.
On Exadata DB systems hosted in Oracle Cloud Infrastructure, each Huge Page is 2 MB
by default. Therefore, to allocate 50 GB of memory to Huge Pages you can execute the
following command:
# sysctl -w vm.nr_hugepages=25600
l At the Oracle Database level, the use of Huge Pages is controlled by the USE_LARGE_
PAGES instance parameter setting. This setting applies to each database instance in a
clustered database. Oracle strongly recommends a consistent setting across all of the
database instances associated with a database. The following options are available:
o TRUE — specifies that the database instance can use Huge Pages if they are
available. For all versions of Oracle Database after 11.2.0.3, Oracle allocates as
much of the SGA as it can, using Huge Pages. When the Huge Page allocation is
exhausted, standard memory pages are used.
o FALSE — specifies that the database instance does not use Huge Pages. This
setting is generally not recommended if Huge Pages are available.
o ONLY — specifies that the database instance must use Huge Pages. With this
setting, the database instance fails to start if the entire SGA cannot be
accommodated in Huge Pages.
If you make any adjustments at either the operating system or Oracle Database level, ensure
that the overall configuration works.
For more information, see the Oracle Database Administrator's Reference for Linux and UNIX-
Based Operating Systems for Release 19, 18, 12.1, or 11.2 for a general overview of Huge
Pages and more information about configuring Huge Pages. Also, see USE_LARGE_PAGES in the
Oracle Database Reference for Release 12.2, 12.1, or 11.2.
Exadata DB System Shapes
This topic describes the available Exadata DB system shapes in Oracle Cloud Infrastructure.
Exadata X8 shapes:
Exadata X7 shapes:
Exadata X6 shapes:
All Exadata shapes provide unlimited I/O, and support only Enterprise Edition - Extreme
Performance. All Exadata shapes provide 720 GB RAM per node except for Exadata base
systems, which provide 360 GB RAM per node. For more details about Exadata shapes, see
System Configuration.
You can manage these systems by using the Console, the API, the Oracle Cloud Infrastructure
CLI, the Database CLI (DBCLI), Enterprise Manager, Enterprise Manager Express, or
SQL Developer.
Note
l Standard Edition
l Enterprise Edition
l Enterprise Edition - High Performance
l Enterprise Edition - Extreme Performance
Two-node Oracle RAC DB systems require Oracle Enterprise Edition - Extreme Performance.
For standard provisioning of DB systems (using Oracle Automatic Storage Management (ASM)
as your storage management software), the supported database versions are:
For fast provisioning of single-node virtual machine database systems (using Logical Volume
Manager as your storage management software), the supported database versions are:
Tip
Preview version DB systems are provisioned in the same manner as non-preview systems. If
available, preview version software is displayed as one of the choices in the Database version
selector in the Create DB System dialog. See To create a DB system for instructions on
provisioning a virtual machine DB system using preview version software.
Preview version software cannot be used for production databases. The following restrictions
apply to preview version software:
l Only available for non-RAC virtual machine DB systems. Preview software is not
available for bare metal systems, Exadata systems, or virtual machine systems using
RAC.
l Uses Logical Volume Manager (LVM) storage management software only. Automatic
Storage Management (ASM) is not available.
l Patching and database version upgrades (including upgrades to the generally available
release of the preview software) are not available.
l You cannot create a new DB system from a backup of a database that uses preview
version software.
l Standalone backups cannot be created.
l Data Guard is not available.
l Preview version software DB systems cannot be created from backups. In-place
restores are supported.
Oracle Cloud Infrastructure currently offers Oracle Database 20c as preview version software.
Warning
When you launch a bare metal DB system, you select a single Oracle Database edition that
applies to all the databases on that DB system. The selected edition cannot be changed. Each
DB system can have multiple database homes, which can be different versions. Each database
home can have only one database, which is the same version as the database home.
When you launch a DB system, you choose a shape, which determines the resources allocated
to the DB system. The available shapes for a bare metal DB system are:
The shape you choose for a bare metal DB system determines its total raw storage, but other
options, like 2- or 3-way mirroring and the space allocated for data files, affect the amount of
usable storage on the system. The following table shows how various configurations affect the
usable storage for bare metal DB systems.
When you launch a virtual machine DB system, you select the Oracle Database edition and
version that applies to the database on that DB system. The selected edition cannot be
changed. Depending on your selected Oracle Database edition and version, your DB system
can support multiple pluggable databases (PDBs). See the following Oracle Database licensing
topics for information about the maximum number of pluggable and container databases
available for your selected Oracle Database version:
Unlike a bare metal DB system, a virtual machine DB system can have only a single Database
Home, which in turn can have only a single database. The databases will be the same version
as the Database Home.
Virtual machine DB systems also differ from bare metal DB systems in the following ways:
l A virtual machine DB system database uses Oracle Cloud Infrastructure block storage
instead of local storage. You specify a storage size when you launch the DB system, and
you can scale up the storage as needed at any time.
l To change the number of CPU cores on an existing virtual machine DB system, you must
change the shape of that DB system. See To change the shape of a virtual machine DB
system for more information.
For 1-node virtual machine DB systems, Oracle Cloud Infrastructure provides have a "fast
provisioning" option that allows you to create your DB system using Logical Volume Manager
as your storage management software. The alternative ("standard provisioning") is to
provision with Oracle Automatic Storage Management (ASM).
Note
When you provision a 2-node RAC DB systems, the system assigns each node to a different
fault domain by default. Using the Advanced Options link in the provisioning dialog, you can
select the fault domain(s) to be used for your 2-node RAC DB systems and the system will
assign the nodes to your selected fault domains. Oracle recommends that you place each node
of a 2-node RAC DB system in a different fault domain. For more information on fault
domains, see Fault Domains.
Virtual machine DB system nodes use underlying physical hosts that periodically need to
undergo maintenance. When such maintenance is needed, Oracle Cloud Infrastructure
schedules a reboot of your virtual machine DB system node and notifies you of the upcoming
reboot. The reboot allows your virtual machine DB system node to be migrated to a new
physical host which is not in need of maintenance. (Stopping and starting the node will also
result in the migration to a new physical host.) The only impact to your virtual machine DB
system node is the reboot itself. The planned maintenance of the original physical hardware
takes place after your node has been migrated to its new host, and has no impact on your DB
system.
If your virtual machine DB system node is scheduled for a maintenance reboot, you can
proactively reboot your node (by stopping and starting it) using the Console or the API. This
lets you control how and when your node experiences downtime. If you choose not to reboot
before the scheduled time, then Oracle Cloud Infrastructure will reboot and migrate your node
at the scheduled time.
To identify the virtual machine DB system nodes that you can proactively reboot, navigate to
your system's DB System Details page in the Console and check the Node Maintenance
Reboot field. If the instance has a maintenance reboot scheduled and can be proactively
rebooted, this field displays the date and start time for the reboot. When the Maintenance
Reboot field does not display a date, your virtual machine DB system has no scheduled node
maintenance events.
To check for scheduled maintenance events using the API, use the GetDbNode operation to
check the timeMaintenanceWindowEnd field of the DbNode resource. This field specifies when
the system will initiate the next scheduled node reboot.
To make it easier to locate nodes that have scheduled maintenance reboots, you can use the
Search service with a predefined query to find all DB systems that have a maintenance reboot
scheduled.
For instructions on using the Console to reboot a node, see To start, stop, or reboot a
DB system.
When you launch a virtual machine DB system, you choose a shape, which determines the
resources allocated to the DB system. After you provision the system, you can change the
shape to adapt to new processing capacity requirements.
The following table shows the available shapes in the X7 series for a virtual machine DB
system.
VM.Standard2.1 1 15 GB
VM.Standard2.2 2 30 GB
VM.Standard2.4 4 60 GB
VM.Standard2.8 8 120 GB
VM.Standard2.16 16 240 GB
VM.Standard2.24 24 320 GB
The following table shows the available shapes in the X5 series for a virtual machine DB
system.
Note
VM.Standard1.1 1 7 GB
VM.Standard1.2 2 14 GB
VM.Standard1.4 4 28 GB
VM.Standard1.8 8 56 GB
VM.Standard1.16 16 112 GB
Virtual machine DB systems use Oracle Cloud Infrastructure block storage. The following
table shows details of the storage options for a virtual machine DB system. Total storage
includes available storage plus recovery logs.
256 712
512 968
1024 1480
2048 2656
4096 5116
6144 7572
8192 10032
10240 12488
12288 14944
14336 17404
16384 19860
18432 22320
20480 24776
22528 27232
24576 29692
26624 32148
28672 34608
30720 37064
32768 39520
34816 41980
36864 44436
38912 46896
40960 49352
For 2-node RAC virtual machine DB systems, storage capacity is shared between the nodes.
Oracle Cloud Infrastructure virtual machine DB systems provisioned using Oracle Linux 7
include a python script, referred to as the Security Technical Implementation Guide (STIG)
tool, that you can use to perform security hardening for your virtual machine DB system. See
Security Technical Implementation Guide (STIG) Tool for Virtual Machine DB systems for
more information.
Backup Options
Oracle Cloud Infrastructure offers you the ability to create and store automatic daily backups
and on-demand full backups. You can store backups in your DB system's local storage, or in
Oracle Cloud Infrastructure Object Storage. See Backing Up a Database for information about
the backup storage options you have for your cloud databases. See Backing Up a Database to
Oracle Cloud Infrastructure Object Storage for information about managed automatic backups
in Oracle Cloud Infrastructure.
See Recovering a Database from Object Storage for information on restoring a database from
a backup in Object Storage.
See To create a DB system from a backup and To create a database from a backup in an
existing DB system for information about creating a new database or DB system from the
following sources:
Note
Before you set up a bare metal or virtual machine DB system, you must set up a virtual cloud
network (VCN) and other Networking service components. This topic describes the
recommended configuration for the VCN.
In general, Oracle recommends using regional subnets, which span all availability domains in
the region. For a bare metal or virtual machine DB system, either a regional subnet or AD-
specific subnet works. For more information, see About Regional Subnets.
You will create a custom route table. You will also create security rules to control traffic to and
from the DB system's compute notes. More information follows about that.
Certain details of the VCN and subnet configuration depend on your choice for DNS resolution
within the VCN. For more information, see DNS for the DB System.
This option can be useful when doing a proof-of-concept or development work. You can use
this setup in production if you want to use an internet gateway with the VCN, or if you have
services that run only on a public network and need access to the database. See the following
diagram and description.
l Public subnet.
l Internet gateway.
l Service gateway to reach Object Storage for database backups and patching. Also see
Option 1: Service Gateway Access Only to Object Storage.
l Route table: A custom route table for the subnet, with two rules:
o A rule for 0.0.0.0/0, and target = internet gateway.
o A rule for the service CIDR label called OCI <region> Object Storage, and
target = the service gateway. Also see Option 1: Service Gateway Access Only to
Object Storage.
l Security rules to enable the desired traffic to and from the DB system nodes. See
Security Rules for the DB System.
Important
Oracle recommends this option for a production system. The subnet is private and cannot be
reached from the internet. See the following diagram and description.
l Private subnet.
l Gateways for the VCN:
o Dynamic routing gateway (DRG), with a FastConnect or IPSec VPN to your on-
premises network.
o Service gateway to reach Object Storage for database backups and patching, and
to reach Oracle YUM repos for OS updates. Also see Option 2: Service Gateway
Access to Both Object Storage and YUM Repos.
o NAT gateway (to reach public endpoints not supported by the service gateway).
l Route table: A custom route table for the subnet, with these rules:
o A route for the on-premises network's CIDR, and target = DRG.
o A rule for the service CIDR label called All <region> Services in Oracle
Services Network, and target = the service gateway. Also see Option 2:
Service Gateway Access to Both Object Storage and YUM Repos.
o If you want to access the Oracle YUM repos through the NAT gateway, add a route
rule for the regional YUM repo's public IP address, and target = the NAT gateway.
If you just use the next rule only, the traffic to the YUM repo would still be routed
to the service gateway, because the service gateway route is more specific than
0.0.0.0/0.
o A rule for 0.0.0.0/0, and target = NAT gateway.
l Security rules to enable the desired traffic to and from the DB system nodes. See
Security Rules for the DB System.
If you are setting up DB systems (and thus VCNs) in more than one region, make sure the IP
address space of the VCNs does not overlap.
The subnet you create for a bare metal or virtual machine DB system cannot overlap with
192.168.16.16/28, which is used by the Oracle Clusterware private interconnect on the
database instance.
Tip
The Networking section of the Console includes a handy wizard that creates a VCN along with
related resources. It can be useful if you just want to try launching an instance. However, the
wizard automatically creates a public subnet and an internet gateway. You may not want this
for your production network, so Oracle recommends you create the VCN and other resources
individually yourself instead of using the wizard.
There are two choices for DNS and hostname resolution for the DB system:
l Recommended: Use the default DNS functionality in the VCN (called the Internet and
VCN Resolver)
l Use a custom DNS resolver of your choice
The following table shows which choices are supported with each type of DB system, and the
endpoints that need to be resolved for the DB system to function.
See the preceding table for the types of DB systems that support the Internet and VCN
Resolver.
Oracle recommends using the Internet and VCN Resolver for DNS. It's the default, built-in
DNS functionality that comes with each VCN. It enables hosts in a VCN to resolve these items:
For general information about the Internet and VCN Resolver, see DNS in Your Virtual Cloud
Network.
For a DB system, the Internet and VCN Resolver handles resolution of all necessary
endpoints: Object Storage endpoints (includes both the Object Storage endpoints and Swift
endpoints), YUM repos, and SCANs (SCANs are used only with 2-node RAC systems).
By default, each VCN is configured to use the Internet and VCN Resolver. If you plan to use a
custom DNS resolver, you must configure the VCN in a different way. For more information,
see Custom DNS Resolver.
The resulting DB system has a fully qualified domain name (FQDN) based on the hostname
prefix, VCN label, and subnet label you specify.
l VCN DNS label
l Subnet DNS label
l Hostname prefix for the DB system
These values make up the node's fully qualified domain name (FQDN):
<hostname_prefix><RAC_node_#>.<subnet_DNS_label>.<VCN_DNS_label>.oraclevcn.com
For RAC systems only, the Database service automatically appends a node number after the
hostname prefix.
For example:
l Node 1: dbsys1.ad1.acmevcniad.oraclevcn.com
l Node 2: dbsys2.ad1.acmevcniad.oraclevcn.com
l The recommended maximums are not enforced when you create the VCN and subnets.
However, the DB system deployment fails if the FQDN has more than 63 characters.
See the preceding table for the types of DB systems that support the use of a custom DNS
resolver.
A custom DNS resolver is a DNS server that you set up in your on-premises network and
maintain yourself. It must resolve the endpoints required by the DB system.
By default, the VCN is configured to use the Internet and VCN Resolver. Therefore, if you
instead want to use a custom DNS resolver, you must configure the VCN and DHCP options in
a different way. See the following process.
Internet and VCN Resolver. Therefore, Oracle recommends that you configure
them now in case you later want to use the Internet and VCN Resolver.
2. Create each subnet with the recommended DNS settings:
l When creating a subnet in the VCN, Oracle recommends that you select select the
check box for Use DNS Hostnames in this Subnet and then specify a DNS
label for the subnet. See the restrictions listed in Hostname restrictions when
using a custom DNS resolver.
l Notice that you cannot change the preceding subnet DNS settings after you create
the subnet. They are optional for a custom DNS server, but required if you use the
Internet and VCN Resolver. Therefore, Oracle recommends that you configure
them now in case you later want to use the Internet and VCN Resolver.
3. Edit the default set of DHCP options to use a custom resolver:
l When creating each subnet, configure it to use the VCN's default set of
DHCP options.
l Edit the default set of DHCP options so that DNS Type is set to Custom
Resolver. Provide the IP address for at least one DNS server (maximum
three). Optionally provide a single search domain (which will automatically be
added to the host's /etc/resolv.conf file).
4. Create the DB system with required DNS entries:
l Later, when creating the DB system, specify a Hostname Prefix.
l For the Host Domain Name: If you selected the check box for Use
DNS Hostnames in the preceding steps, the Host Domain Name is
automatically generated from the VCN and subnet DNS labels. Otherwise, you
must provide a value for the Host Domain Name. See the restrictions listed in
Hostname restrictions when using a custom DNS resolver.
l Notice that when launching the DB system, the Database service automatically
assigns an IP address from the VCN's CIDR block and resolves the address locally
based on the host's /etc/hosts file. Your custom DNS resolver does not need to
resolve the hostname in advance for the DB system launch to succeed.
l You can provide a value for the DNS labels only if you select the check box for Use DNS
Hostnames when creating the VCN and subnets. The resulting FQDN for the DB system
follows this format:
<hostname_prefix>.<subnet_DNS_label>.<VCN_DNS_label>.oraclevcn.com
l The recommended maximums are not enforced when you create the VCN and subnets.
However, the DB system deployment fails if the FQDN has more than 63 characters.
l You can provide a value in the Host Domain Name field only if you did not select the
check box for Use DNS Hostnames when creating the VCN and subnets.
l No hyphens or underscores.
l Ensure that the value results in an FQDN that is no longer than 63 characters. Otherwise
the DB system deployment will fail.
If you are using the Internet and VCN Resolver and want to enable the use of hostnames when
on-premises hosts and VCN resources communicate with each other, you can set up an
instance in the VCN to be a custom DNS server. For an example of an implementation of this
scenario with the Oracle Terraform provider, see Hybrid DNS Configuration.
Your VCN needs access to both Object Storage (for backing up databases, patching, and
updating the cloud tooling on a DB system) and Oracle YUM repos for OS updates.
Depending on whether you use option 1 or option 2 described previously, you use the service
gateway in different ways. See the next two sections.
l Perform the tasks for setting up a service gateway on a VCN, and specifically enable the
service CIDR label called OCI <region> Object Storage.
l In the task for updating routing, add a route rule to the subnet's custom route table. For
the destination service, use OCI <region> Object Storage and target = the service
gateway.
l In the task for updating security rules for the subnet, perform the task on the DB
system's custom network security group (NSG) or security list. Here you set up a
security rule with the destination service set to OCI <region> Object Storage. See
Custom Security Rules.
Option 2: Service Gateway Access to Both Object Storage and YUM Repos
You configure the subnet to use the service gateway for access to the Oracle Services
Network, which includes both Object Storage and the Oracle YUM repos.
Important
l Perform the tasks for setting up a service gateway on a VCN, and specifically enable the
service CIDR label called All <region> Services in Oracle Services Network.
l In the task for updating routing in the subnet, add a rule to the subnet's custom route
table. For the destination service, use All <region> Services in Oracle Services
Network and target = the service gateway.
l In the task for updating security rules for the subnet, perform the task on the subnet's
custom network security group (NSG) or security list. Here you set up a security rule
with the destination service set to All <region> Services in Oracle Services
Network. See Custom Security Rules.
This section lists the security rules to use with your DB system. Security rules control the
types of traffic allowed in and out of the DB system's compute nodes. The rules are divided
into two sections.
There are different ways to implement these rules. For more information, see Ways to
Implement the Security Rules.
Important
This section has several general rules that enable essential connectivity for hosts in the VCN.
If you use security lists to implement your security rules, be aware that the rules that follow
are included by default in the default security list. Update or replace the list to meet your
particular security needs. The two ICMP rules (general ingress rules 2 and 3) are required for
proper functioning of network traffic within the Oracle Cloud Infrastructure environment.
Adjust the general ingress rule 1 (the SSH rule) and the general egress rule 1 to allow traffic
only to and from hosts that require communication with resources in your VCN.
General ingress rule 3: Allows connectivity error messages within the VCN
This rule enables the hosts in the VCN to receive connectivity error messages from each
other.
Important
Custom ingress rule 1: Allows ONS and FAN traffic from within the VCN
This rule is recommended and enables the Oracle Notification Services (ONS) to communicate
about Fast Application Notification (FAN) events.
Custom ingress rule 2: Allows SQL*NET traffic from within the VCN
This rule is for SQL*NET traffic and is required only if you need to enable client connections to
the database.
Custom egress rule 2: Allows access to Object Storage and YUM repos
This rule enables the DB system to communicate with Object Storage alone (for option 1), or
with the Oracle Services Network, which includes both Object Storage and the Oracle YUM
repos (for option 2). It is redundant with the general egress rule in General Rules Required for
Basic Connectivity (and in the default security list). It is optional but recommended in case the
general rule (or default security list) is inadvertently changed.
The Networking service offers two ways to implement security rules within your VCN:
For a comparison of the two methods, see Comparison of Security Lists and Network Security
Groups.
1. Create a network security group for DB systems. Add the following security rules to that
NSG:
l The rules listed in General Rules Required for Basic Connectivity
l The rules listed in Custom Security Rules
2. When the database administrator creates the DB system, they must choose several
networking components (for example, which VCN and subnet to use). They can also
choose which NSG or NSGs to use. Make sure they choose the NSG you created.
You could instead create one NSG for the general rules and a separate NSG for the custom
rules. Then when the database administrator chooses which NSGs to use for the DB system,
make sure they choose both NSGs.
Warning
When you launch a DB system using the Console, the API, or the CLI, the system is
provisioned to support Oracle databases and an initial database is created based on the
options you provide and some default options described later in this topic.
Warning
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: The policy in Let database admins manage DB systems lets the specified
group do everything with databases and related Database resources.
If you're new to policies, see Getting Started with Policies and Common Policies. If you want
to dig deeper into writing policies for databases, see Details for the Database Service.
Prerequisites
l The public key, in OpenSSH format, from the key pair that you plan to use for
connecting to the DB System via SSH. A sample public key, abbreviated for readability,
is shown below.
ssh-rsa AAAAB3NzaC1yc2EAAAABJQAA....lo/gKMLVM2xzc1xJr/Hc26biw3TXWGEakrK1OQ== rsa-key-20160304
must also be configured as necessary for the DB system. For more information, see
Network Setup for DB Systems.
l If you plan to back up your DB system to Object Storage or to use the managed patching
feature, Oracle recommends using a service gateway to enable access to Object
Storage. For more information, see Service Gateway for the VCN.
l For a 2-node RAC DB system, ensure that port 22 is open for both ingress and egress on
the subnet, and that the security rules you create are stateful (the default), otherwise,
the DB system might fail to provision successfully.
To simplify launching a DB system in the Console and when using the API, the following
default options are used for the initial database and for any additional databases that you
create. (Several advanced options such as Time Zone can be set when you can use the dbcli
command line interface to create databases.)
For a list of the database options that you can set, see To launch a DB system.
To launch a DB system
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
3. Click Launch DB System.
4. In the Launch DB System dialog, enter the following:
DB SYSTEM INFORMATION
Note
l Cluster Name: A unique cluster name for a multi-node DB system. The name
must begin with a letter and contain only letters (a-z and A-Z), numbers (0-9) and
hyphens (-). The cluster name can be no longer than 11 characters and is not case
sensitive.
l Total Node Count: Virtual machine DB systems only. The number of nodes in
the DB system. The number depends on the shape you select. You can specify 1 or
2 nodes for virtual machine DB systems, except for VM.Standard2.1 and
VM.Standard1.1, which are single-node DB systems.
l Oracle Database Software Edition: The database edition supported by the DB
system. For bare metal systems, you can mix supported database releases on the
DB system to include older database versions, but not editions. The database
edition cannot be changed and applies to all the databases in this DB system.
Virtual machine systems support only one database.
l Available Storage Size: Virtual machine DB systems only. The amount of Block
Storage you wish to allocate to the virtual machine DB system.
l Cluster Name: A unique cluster name for a multi-node DB system. The name
must begin with a letter and contain only letters (a-z and A-Z), numbers (0-9) and
hyphens (-). The cluster name can be no longer than 11 characters and is not case
sensitive.
l CPU Core Count: The number of CPU cores for the DB system. Displays only if
you select a shape that allows you to configure the number of cores. The text
below the field indicates the acceptable values for that shape. For a multi-node
DB system, the core count is evenly divided across the nodes.
Except for virtual machine DB systems, you can increase the CPU cores to
accommodate increased demand after you launch the DB system.
l License Type: The type of license you want to use for the DB system. Your
choice affects metering for billing.
o License included means the cost of this Oracle Cloud Infrastructure
Database service resource will include both the Oracle Database software
licenses and the service.
o Bring Your Own License (BYOL) means you will use your organization's
Oracle Database software licenses for this Oracle Cloud Infrastructure
Database service resource. See Bring Your Own License for more
information.
l SSH Public Key: The public key portion of the key pair you want to use for SSH
access to the DB system. To provide multiple keys, paste each key on a new line.
Make sure each key is on a single, continuous line. The length of the combined
keys cannot exceed 10,000 characters.
l Data Storage Percentage: For bare metal DB systems only. The percentage
(40% or 80%) assigned to DATA storage (user data and database files). The
remaining percentage is assigned to RECO storage (database redo logs, archive
logs, and recovery manager backups).
l Available Storage Size: For virtual machine DB systems only. The amount of
block storage to allocate to the virtual machine DB system. Available storage can
be scaled up or down as needed after provisioning your DB system.
l Advanced Options: For bare metal DB systems only.
o Disk Redundancy: For bare metal systems only. The type of redundancy
configured for the DB system.
n Normal is 2-way mirroring, recommended for test and development
systems.
n High is 3-way mirroring, recommended for production systems.
NETWORK INFORMATION
Important
l Host Domain Name: The domain name for the DB system. If the selected
subnet uses the Oracle-provided Internet and VCN Resolver for DNS name
resolution, this field displays the domain name for the subnet and it can't be
changed. Otherwise, you can provide your choice of a domain name. Hyphens (-)
are not permitted.
l Host and Domain URL: Combines the host and domain names to display the
fully qualified domain name (FQDN) for the database. The maximum length is 64
characters.
DATABASE INFORMATION
l Database Name: The name for the database. The database name must begin
with an alphabetic character and can contain a maximum of eight alphanumeric
characters. Special characters are not permitted.
l Database Version: The version of the initial database created on the DB system
when it is launched. After the DB system is active, you can create additional
databases on it. You can mix database versions on the DB system, but not
editions.
If you are launching a DB system with a virtual machine shape, you have option of
selecting an older database version. Check Display all database versions to
include older database versions in the drop-down list of database version choices.
See Availability of Older Database Versions for Virtual Machine DB Systems for
more information.
Note
l PDB Name: Not applicable to version 11.2.0.4. The name of the pluggable
database. The PDB name must begin with an alphabetic character, and can
contain a maximum of 8 alphanumeric characters. The only special character
permitted is the underscore ( _).
l Database Admin Password:
A strong password for SYS, SYSTEM, TDE wallet, and PDB Admin. The password
must be 9 to 30 characters and contain at least two uppercase, two lowercase,
two numeric, and two special characters. The special characters must be _, #, or
-. The password must not contain the username (SYS, SYSTEM, and so on) or the
word "oracle" either in forward or reversed order and regardless of casing.
l Confirm Database Admin Password: Re-enter the Database Admin Password
you specified.
l Automatic Backup: (Optional) If you enable automatic backups, you can choose
one of the following preset retention periods: 7 days, 15 days, 30 days, 45 days,
or 60 days. The default selection is 30 days.
l Database Workload:
Select the workload type that best suits your application.
o Online Transactional Processing (OLTP) configures the database for a
transactional workload, with a bias towards high volumes of random data
access.
o Decision Support System (DSS) configures the database for a decision
support or data warehouse workload, with a bias towards large data
scanning operations.
l Character Set: The character set for the database. The default is AL32UTF8.
Advanced Options:
o Character Set: The character set for the database. The default is
AL32UTF8.
o National Character Set: The national character set for the database. The
default is AL16UTF16.
o Fault Domain: The fault domain(s) in which the DB system resides. You
can choose which fault domain to use for your DB system. For 2-node RAC
DB systems, you can specify which two fault domains are to be used. Oracle
recommends that you place each node of a 2-node RAC DB system in a
different fault domain. For more information on fault domains, see Fault
Domains.
l Tags: Optionally, you can apply 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.
5. Click Launch DB System.
The DB system appears in the list with a status of Provisioning. The DB system's icon
changes from yellow to green (or red to indicate errors).
6. Wait for the DB system's icon to turn green, with a status of Available, and then click
l When you launch a new DB system from a backup, the availability domain will be the
same as where the backup is hosted.
l The shape you specify must be the same type as the database from which the backup
was taken. For example, if you are using a backup of a 1-node database, then the DB
system you select as your target must also be a 1-node DB system.
l The Oracle database software edition you specify must be an equal or greater edition
than that of the backed up database.
l If you specify a virtual machine DB system shape, the Available Storage Size will
default to the data size of the backup, rounded up to the closest storage size option.
However, you can specify a larger storage size.
l If you are creating a database from an automatic backup, you may choose any level 0
weekly backup, or a level 1 incremental backup created after the most recent level 0
backup. For more information on automatic backups, see Automatic Incremental and
Archived Redo Log Backups
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
A list of DB systems is displayed.
3. Navigate to the backup you wish to use to create a new database. You can select a
backup from a database details page, or select a backup that appears in your
compartment's list of standalone backups.
4. Click the Actions icon (three dots) for the backup you are interested in, and then click
Create Database.
5. In the Create Database from Backup dialog, enter the following:
DB SYSTEM INFORMATION
Note
l Total Node Count: Virtual machine DB systems only. The number of nodes in
the DB system. The number depends on the shape you select. You can specify 1 or
2 nodes for virtual machine DB systems, except for VM.Standard2.1 and
VM.Standard1.1, which are single-node DB systems.
l Oracle Database Software Edition: The database edition supported by the DB
system. For bare metal systems, you can mix supported database releases on the
DB system to include older database versions, but not editions. The database
edition cannot be changed and applies to all the databases in this DB system.
Virtual machine systems support only one database.
l Available Storage Size: Virtual machine DB systems only. The amount of Block
Storage you wish to allocate to the virtual machine DB system.
l Cluster Name: A unique cluster name for a multi-node DB system. The name
must begin with a letter and contain only letters (a-z and A-Z), numbers (0-9) and
hyphens (-). The cluster name can be no longer than 11 characters and is not case
sensitive.
l License Type: The type of license you want to use for the DB system. Your
choice affects metering for billing.
NETWORK INFORMATION
Important
DATABASE INFORMATION
l Database Name: The name for the database. The database name must begin
with an alphabetic character and can contain a maximum of eight alphanumeric
characters. Special characters are not permitted.
l Database Admin Password:
A strong password for SYS, SYSTEM, TDE wallet, and PDB Admin. The password
must be 9 to 30 characters and contain at least two uppercase, two lowercase,
two numeric, and two special characters. The special characters must be _, #, or
-. The password must not contain the username (SYS, SYSTEM, and so on) or the
word "oracle" either in forward or reversed order and regardless of casing.
l Confirm Database Admin Password: Re-enter the Database Admin Password
you specified.
l Password for Transparent Data Encryption (TDE) Wallet or RMAN
Encryption:
Enter either the TDE wallet password or the RMAN encryption password for the
backup, whichever is applicable. The TDE wallet password is the SYS password
provided when the database was created by using the Oracle Cloud Infrastructure
Console, API, or CLI. The RMAN encryption password is typically required instead
if the password was subsequently changed manually.
6. Click Create Database.
7. Optionally, you can apply 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.
l Provisioning: Yellow icon. Resources are being reserved for the DB system, the
system is booting, and the initial database is being created. Provisioning can take
several minutes. The system is not ready to use yet.
l Available: Green icon. The DB system was successfully provisioned. A few
minutes after the system enters this state, you can SSH to it and begin using it.
l Terminating: Gray icon. The DB system is being deleted by the terminate action
in the Console or API.
l Terminated: Gray icon. The DB system has been deleted and is no longer
available.
l Failed: Red icon. An error condition prevented the provisioning or continued
operation of the DB system.
To view the status of a database node, under Resources, click Nodes to see the list of
nodes. In addition to the states listed for a DB system, a node's status can be one of the
following:
l Starting: Yellow icon. The database node is being powered on by the start or
reboot action in the Console or API.
l Stopping: Yellow icon. The database node is being powered off by the stop or
reboot action in the Console or API.
l Stopped: Yellow icon. The database node was powered off by the stop action in
the Console or API.
You can also check the status of DB systems and database nodes by using the ListDbSystems
or ListDbNodes API operations, which return the lifecycleState attribute.
Tip
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
A list of DB systems is displayed.
3. In the list of DB systems, find the DB system you want to stop or start, and then click its
name to display details about it.
4. In the list of nodes, click the Actions icon (three dots) for a node and then click one of
the following actions:
l Start: Restarts a stopped node. After the node is restarted, the Stop action is
enabled.
l Stop: Shuts down the node. After the node is powered off, the Start action is
enabled.
l Reboot: Shuts down the node, and then restarts it.
Note
Note
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
A list of DB systems is displayed.
3. In the list of DB systems, find the system you want to scale and click its highlighted
name.
The system details are displayed.
4. Click Scale Up/Down and then change the number in Total CPU Core Count. The
text below the field indicates the acceptable values, based on the shape used when the
DB system was launched.
5. Click Scale Up/Down DB System.
Note
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
To terminate a DB system
Terminating a DB system permanently deletes it and any databases running on it.
Note
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
A list of DB systems is displayed.
3. For the DB system you want to terminate, click the Actions icon (three dots) and then
click Terminate.
4. Confirm when prompted. .
The DB system's icon indicates Terminating.
At this point, you cannot connect to the system and any open connections will be terminated.
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
A list of DB systems is displayed.
3. In the list of DB systems, find the system you want to scale and click its highlighted
name.
The system details are displayed.
4. Click Scale Up/Down OCPU, and then change the number.
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.
DB systems:
l ListDbSystems
l GetDbSystem
l LaunchDbSystem
l TerminateDbSystem
Database homes:
l ListDbHomes
l GetDbHome
l CreateDbHome
l DeleteDbHome
Databases:
l ListDatabases
l GetDatabase
Nodes:
l ListDbSystemShapes
l ListDbVersions
For the complete list of APIs for the Database service, see Database Service API.
DNS lets you use host names instead of IP addresses to communicate with a DB system. You
can use the Internet and VCN Resolver (the DNS capability built into the VCN) as described in
DNS in Your Virtual Cloud Network.
Alternatively, you can use your choice of DNS server. You associate the host name and
domain name to the public or private IP address of the DB system. You can find the host and
domain names and IP addresses for the DB system in the Oracle Cloud Infrastructure Console
on the Database page.
To associate the host name to the DB system's public or private IP address, contact your
DNS administrator and request a custom DNS record for the DB system’s IP address. For
example, if your domain is example.com and you want to use clouddb1 as the host name, you
would request a DNS record that associates clouddb1.example.com to your DB system's IP
address.
If you provide the public IP address to your DNS administrator as described above, you should
also associate a custom domain name to the DB system's public IP address:
1. Register your domain name through a third-party domain registration vendor, such as
register.com.
2. Resolve your domain name to the DB system's public IP address, using the third-party
domain registration vendor console. For more information, refer to the third-party
domain registration documentation.
Connecting to a DB System
This topic explains how to connect to an active DB system. How you connect depends on the
client tool or protocol you use, the purpose of the connection, and how your cloud network is
set up. You can find information on various networking scenarios in Overview of Networking,
but for specific recommendations on how you should connect to a database in the cloud,
contact your network security administrator.
Prerequisites
This section describes prerequisites you'll need to perform various tasks in this topic.
l To use the Console or the API to get the default administration service connection
strings, 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. See Authentication
and Authorization for more information on user authorizations for the Oracle Cloud
Infrastructure Database service.
l To connect to the database, you'll need the public or private IP address of the DB
system. Use the private IP address to connect to the DB system from your on-premises
network, or from within the virtual cloud network (VCN). This includes connecting from
a host located on-premises connecting through a VPN or FastConnect to your VCN, or
from another host in the same VCN. Use the DB System's public IP address to connect
to the system from outside the cloud (with no VPN). You can find the IP addresses in the
Oracle Cloud Infrastructure Console on the DB System Details page by clicking
Nodes under the Resources list. The values are displayed in the Public IP Address
and Private IP Address & DNS Name columns of the Nodes table.
l For Secure Shell (SSH) access to the DB system, you'll need the full path to the file that
contains the private key associated with the public key used when the DB system was
launched.
Database services allow you to control client access to a database instance depending on the
functionality needed. For example, you might need to access the database for administration
purposes only or you might need to connect an application to the database. Connection strings
are specific to a database service.
l Workload identification
l Load balancing
l Application continuity and Transaction Guard
l Fast Application Notification
l Resource assignment based on the service name
For details about these and other High Availability capabilities, see Client Failover Best
Practices for Highly Available Oracle Databases.
You use the srvctl utility to create an application service. Before you can connect to the
service, you must start it.
3. Create the application service for the database. Include the pdb option only if you are
creating an application service for a PDB.
$ srvctl add service
-db <DB_unique_name>
-pdb <PDB_name>
-service <app_service_name>
-role PRIMARY
-notification TRUE
-session_state dynamic
-failovertype transaction
-failovermethod basic
-commit_outcome TRUE
-failoverretry 30
-failoverdelay 10
-replay_init_time 900
-clbgoal SHORT
-rlbgoal SERVICE_TIME
-preferred <rac_node1>,<rac_node2>
-retention 3600
Note that the preferred option is required only for multi-node databases to specify the
hostname of the node in the RAC.
4. Start the application service.
$ srvctl start service -db <DB_unique_name> -s <app_service_name>
For more information about services for a PDB, see Managing Services for PDBs.
You must use the appropriate connection string to access a database administration or
application service. You can use the Console or the API to get the string for connecting to the
default administration service from within a VCN. For 12c and later Oracle Databases, this
service is for administrating the database at the CDB level. The string is provided in both the
Easy Connect and in the full connect descriptor (long) format. Use the long format for the
connection if hostname resolution is not available. You can also use the long format to create
an alias in the tnsnames.ora file.
For accessing a database service within the VCN, the connection string for a Real Application
Cluster (RAC) DB system uses the Single Client Access Name (SCAN) while the connection
string for single instance DB system uses the hostname instead.
The private SCAN name is a Round Robin DNS entry created when you launch a 2-node RAC
DB system. The private SCAN name is resolvable only within the VCN. If the client and the
database are in the same VCN, the connection mechanism is the same as an on-premises RAC
database; all the features provided by VIPs and SCAN VIPs, such as server side load balancing
and VIP failover, are available.
Note
You can derive the connection strings for other database services by replacing part of the
default application service connection string with the applicable values.
This section describes how to connect to a database service from a computer that has a
SQL*Net client installed. Port 1521 must be open to support the SQL*Net protocol.
For security reasons, Oracle recommends that you connect to your database services from
within the VCN. You can use this method whether you are connecting to an administration
service or to an application service.
To connect using SQL*Plus, you run the following command using the applicable connection
string:
sqlplus system/<password>@<connection_string>
l If your system is not using the VCN Resolver, ensure that the DB system's hostname
(for single-node systems) or SCAN name (for multi-node systems) can be resolved. See
DNS in Your Virtual Cloud Network for information about DNS name resolution.
l For connecting to the administration service of a PDB, ensure that the PDB is open or
the service will not be available.
l For connecting to an application service, ensure that the service is started. For Fast
Application Notification to work, ensure that port 6200 can be reached. See Client
Failover Best Practices for Highly Available Oracle Databases for information about Fast
Application Notification.
Although Oracle does not recommend connecting to your database from the Internet, you can
connect to a database service by using a public IP address if port 1521 is open to the public for
ingress.
To use this method, you run the following command using the public IP address instead of the
hostname or SCAN in the connection string:
sqlplus system/<password>@<public_IP>:1521/<service_name>.<DB_domain>
l SCANs and hostnames are not resolvable on the Internet, therefore load balancing and
failover for multi-node DB systems, which rely on these names, cannot work.
l For multi-node DB systems, which normally use SCANs, you must specify the IP
address of one of the RAC hosts to access the database.
Important
Prerequisites:
l Ensure that port 1521 is open for the Oracle default listener. (You can do this by
checking the DB system's security list.)
l If port 1521 is open only to hosts in the VCN, then you must run your SQL Developer
client from a machine that has direct access to the VCN. If you are connecting to the
database from the Internet instead, then the public IP address of your computer must
be granted access to port 1521 in the security list. (Alternatively, the security list can
grant full access to port 1521, however, this is not recommended for security reasons.)
You must use the public IP address of the host because connecting from the Internet
does not support SCAN name resolution.
l When the client uses the public IP address, the client bypasses the SCAN listener and
reaches the node listener, so server side load balancing is not available.
l When the client uses the public IP address, it cannot take advantage of the VIP failover
feature. If a node becomes unavailable, new connection attempts to the node will hang
until a TCP/IP timeout occurs. You can set client side SQL*Net parameters to limit the
TCP/IP timeout.
The following tnsnames.ora example shows a connection string that includes the CONNECT_
TIMEOUT parameter. This parameter controls the TCP timeout for connecting to a node.
test=
(DESCRIPTION =
(CONNECT_TIMEOUT=3)
(ADDRESS_LIST=
(ADDRESS = (PROTOCOL = TCP)(HOST = <public_IP1>)(PORT = 1521))
(ADDRESS = (PROTOCOL = TCP)(HOST = <public_IP2>)(PORT = 1521))
)
(CONNECT_DATA =
(SERVER = DEDICATED)
(SERVICE_NAME = <dbservice.subnetname.dbvcn.oraclevcn.com>)
)
)
For more information about using the CONNECT_TIMEOUT parameter, see Client Failover Best
Practices for Highly Available Oracle Databases.
You can access the services of DB system databases with public IP addresses by using SSH
tunneling. The main advantage of this method is that port 1521 does not need to be opened to
the public internet. However, just like accessing the database with a public IP using a SQL*Net
client, load balancing and failover for multi-node DB systems cannot work because they rely
on SCANs and hostnames.
Oracle SQL Developer and Oracle SQLcL and are two tools that facilitate the use of tunneling
for Oracle Database access.
To open a tunnel, and then connect to a database service by using SQLcL, you run commands
like the following:
SQL> sshtunnel opc@<public_IP> -i <private_key> -L <local_port>:<private_IP>:1521
Using port:22
SSH Tunnel connected
SQL> connect system/<password>@localhost:<local_port>/<service_name>.<DB_domain>
See Oracle SQL Developer and Oracle SQLcL for information about these tools.
This method allows you to connect to the database without using the network listener. It
should be used to connect only for administration purposes.
When connecting to a multi-node DB system, you'll SSH to each individual node in the cluster.
<private_key> is the full path and name of the file that contains the private key associated
with the DB system you want to access.
Use the DB system's private or public IP address depending on your network configuration.
For more information, see Prerequisites.
3. Connect as the oracle user and get the details about one of the databases by using the
srvctl command.
[root@ed1db01 ~]# su - oracle
[oracle@ed1db01 ~]$ . oraenv
ORACLE_SID = [oracle] ? cdbm01
The Oracle base has been set to /u02/app/oracle
[oracle@ed1db01 ~]$ srvctl config database -d cdbm01
Database unique name: cdbm01 <<== DB unique name
Database name:
Oracle home: /u02/app/oracle/product/12.1.0/dbhome_2
Oracle user: oracle
Spfile: +DATAC1/cdbm01/spfilecdbm01.ora
Password file: +DATAC1/cdbm01/PASSWORD/passwd
Domain: data.customer1.oraclevcn.com
Start options: open
Stop options: immediate
Database role: PRIMARY
Management policy: AUTOMATIC
Server pools:
Disk Groups: DATAC1,RECOC1
Mount point paths:
Services:
Type: RAC
Start concurrency:
Stop concurrency:
OSDBA group: dba
OSOPER group: racoper
Database instances: cdbm011,cdbm012 <<== SID
Configured nodes: ed1db01,ed1db02
Database is administrator managed
4. Set the ORACLE_SID and ORACLE_UNIQUE_NAME using the values from the previous
step.
[oracle@ed1db01 ~]$ export ORACLE_UNIQUE_NAME=cdbm01
[oracle@ed1db01 ~]$ export ORACLE_SID=cdbm011
[oracle@ed1db01 ~]$ sqlplus / as sysdba
Connected to:
Oracle Database 12c EE Extreme Perf Release 12.1.0.2.0 - 64bit Production
With the Partitioning, Real Application Clusters, Automatic Storage Management, Oracle Label
Security,
OLAP, Advanced Analytics and Real Application Testing options
You can create and delete serial console connections to your bare metal or virtual machine DB
system in the Oracle Cloud Infrastructure Console. This allows you to manage and
troubleshoot your system in single-user mode using an SSH connection. See the following
topics for more information:
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.
Use the GetDatabase API operation to get the default administration service connection
strings.
For a 1-node DB system or 2-node RAC DB system, regardless of how you connect to the DB
system, before you use OS authentication to connect to a database (for example, sqlplus /
as sysdba) be sure to set the ORACLE_UNQNAME variable. Otherwise, commands that
require the TDE wallet will result in the error ORA-28365: wallet is not open.
Note that this is not an issue when using a TNS connection because ORACLE_UNQNAME is
automatically set in the database CRS resource.
If the DB system’s root volume becomes full, you might lose the ability to SSH to the system
(the SSH command will fail with permission denied errors). Before you copy a large amount
of data to the root volume, for example, to migrate a database, use the dbcli create-
dbstorage command to set up storage on the system’s NVMe drives and then copy the
database files to that storage. For more information, see Setting Up Storage on the
DB System.
WHAT NEXT?
Before you begin updating your DB system, review the information in Updating a DB System.
For information about setting up an Enterprise Manager console to monitor your databases,
see Monitoring a Database.
Updating a DB System
Note
This topic includes information and instructions on how to update the OS of a bare metal or
virtual machine DB system.
Warning
Do not add interactive commands such as oraenv, or commands that might return an error or
warning message, to the .bash_profile file for the grid or oracle users. Adding such
commands can prevent Database service operations from functioning properly.
For a 1-node DB system or 2-node RAC DB system, do not remove or modify the following
firewall rules in /etc/sysconfig/iptables:
l The firewall rules for ports 1521, 7070, and 7060 allow the Database service to manage
the DB system. Removing or modifying them can result in the Database Service no
longer operating properly.
l The firewall rules for 169.254.0.2:3260 and 169.254.0.3:80 prevent non-root users from
escalating privileges and tampering with the system’s boot volume and boot process.
Removing or modifying these rules can allow non-root users to modify the system's
boot volume.
OS Updates
Before you update the OS, review the following important guidelines and information:
Warning
l Oracle recommends that you test any updates thoroughly before updating a production
system.
l The image used to launch a DB system is updated regularly with the necessary patches.
After you launch a DB system, you are responsible for applying the required OS security
updates published through the Oracle public YUM server.
Note
1. Log on to the DB system host as opc, and then sudo to the root user.
login as: opc
[opc@dbsys ~]$ sudo su -
2. If your DB system uses an image with the kernel version 4.1.12-124.27.1.el7uek (used
with older images), then change the bootefi label before updating the OS.
If you have kernel version 4.1.12-124.27.1.el7uek, then proceed to change the bootefi
label.
Example:
LABEL=BOOTEFI /boot/efi vfat defaults 1 2
4. With the region you noted from the previous step, determine the region name, and
perform the following two steps.
See Regions and Availability Domains to look up the region name.
a. Download the repo.
# wget https://swiftobjectstorage.<region_
name>.oraclecloud.com/v1/dbaaspatchstore/DBaaSOSPatches/oci_dbaas_ol7repo -O /tmp/oci_
dbaas_ol7repo
100%
[=========================================================================================
==========================================================================================
===================================================>] 1,394 --.-K/s in 0s
100%
[=========================================================================================
==========================================================================================
===================================================>] 15,769 --.-K/s in 0.1s
The initial version lock file should be empty. However, it is a good practice to back it up
in case it is not and you need to refer to it later.
7. Run the update command.
| 18 MB 00:00
# yum update
Loaded plugins: kernel-update-handler, ulninfo, versionlock
Excluding 250 updates due to versionlock (use "yum versionlock status" to show them)
Resolving Dependencies
--> Running transaction check
---> Package kernel-uek.x86_64 0:4.1.12-124.28.5.el7uek will be installed
---> Package kernel-uek-firmware.noarch 0:4.1.12-124.28.5.el7uek will be installed
---> Package libtalloc.x86_64 0:2.1.10-1.el7 will be updated
---> Package libtalloc.x86_64 0:2.1.13-1.el7 will be an update
---> Package pytalloc.x86_64 0:2.1.10-1.el7 will be updated
---> Package pytalloc.x86_64 0:2.1.13-1.el7 will be an update
--> Finished Dependency Resolution
Dependencies Resolved
=================================================================================================
======================================
Package Arch Version
Repository Size
=================================================================================================
======================================
Installing:
kernel-uek x86_64 4.1.12-124.28.5.el7uek
ol7_UEKR4 44 M
kernel-uek-firmware noarch 4.1.12-124.28.5.el7uek
ol7_UEKR4 1.0 M
Updating:
libtalloc x86_64 2.1.13-1.el7
ol7_latest 31 k
Transaction Summary
=================================================================================================
======================================
Install 2 Packages
Upgrade 2 Packages
Note
Note
1. Log on to the DB system host as opc, and then sudo to the root user.
login as: opc
[opc@dbsys ~]$ sudo su -
3. With the region you noted from the previous step, determine the region name, and
perform the following two steps.
See Regions and Availability Domains to look up the region name.
a. Download the repo.
# wget https://swiftobjectstorage.<region_
name>.oraclecloud.com/v1/dbaaspatchstore/DBaaSOSPatches/oci_dbaas_ol6repo -O /tmp/oci_
dbaas_ol6repo
100%
[=========================================================================================
==========================================================================================
===================================================>] 1,394 --.-K/s in 0s
100%
[=========================================================================================
==========================================================================================
===================================================>] 15,769 --.-K/s in 0.1s
b. Modify the ol6.repo file to enable the repo for your region.
vi /etc/yum.repos.d/ol6.repo
[ol6_latest_PHX]
name=Oracle Linux $releasever Latest ($basearch)
baseurl=http://yum-phx.oracle.com/repo/OracleLinux/OL6/latest/$basearch/
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-oracle
gpgcheck=1
enabled=1 <= Enabled.
[ol6_UEKR4_PHX]
name=Latest Unbreakable Enterprise Kernel Release 4 for Oracle Linux $releasever
($basearch)
baseurl=http://yum-phx.oracle.com/repo/OracleLinux/OL6/UEKR4/$basearch/
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-oracle
gpgcheck=1
enabled=1 <= Enabled.
5. Install yum-plugin-versionlock.
$ sudo su -
# yum repolist
Loaded plugins: kernel-update-handler, security, ulninfo
ol6_UEKR4
| 1.2 kB 00:00
ol6_UEKR4/primary
| 29 MB 00:00
ol6_UEKR4
588/588
ol6_latest
| 1.4 kB 00:00
ol6_latest/primary
| 67 MB 00:00
ol6_latest
39825/39825
repo id repo name
status
ol6_UEKR4 Latest Unbreakable Enterprise Kernel Release 4 for Oracle
Linux 6Server (x86_64) 588
ol6_latest Oracle Linux 6Server Latest (x86_64)
39825
repolist: 40413
Dependencies Resolved
=================================================================================================
=====================================================
Package Arch Version
Repository Size
=================================================================================================
=====================================================
Installing:
yum-plugin-versionlock noarch 1.1.30-40.0.1.el6
ol6_latest 32 k
Transaction Summary
=================================================================================================
=====================================================
Install 1 Package(s)
Is this ok [y/N]: y
Running rpm_check_debug
Running Transaction Test
Transaction Test Succeeded
Running Transaction
Warning: RPMDB altered outside of yum.
** Found 4 pre-existing rpmdb problem(s), 'yum check' output follows:
oda-hw-mgmt-12.2.0.1.0_LINUX.X64_170614.TR1221-1.x86_64 has missing requires of
/usr/local/bin/perl
oda-hw-mgmt-12.2.0.1.0_LINUX.X64_170614.TR1221-1.x86_64 has missing requires of libnfsodm12.so()
(64bit)
oda-hw-mgmt-12.2.0.1.0_LINUX.X64_170614.TR1221-1.x86_64 has missing requires of perl
(GridDefParams)
oda-hw-mgmt-12.2.0.1.0_LINUX.X64_170614.TR1221-1.x86_64 has missing requires of perl(s_GridSteps)
Installing : yum-plugin-versionlock-1.1.30-40.0.1.el6.noarch
1/1
Verifying : yum-plugin-versionlock-1.1.30-40.0.1.el6.noarch
1/1
Installed:
yum-plugin-versionlock.noarch 0:1.1.30-40.0.1.el6
Complete!
Note
The initial version lock file should be empty. However, it is a good practice to back it up
in case it is not and you need to refer to it later.
7. Run the update command.
# yum update
Loaded plugins: kernel-update-handler, security, ulninfo, versionlock
Setting up Update Process
Resolving Dependencies
--> Running transaction check
---> Package kernel-uek.x86_64 0:4.1.12-112.14.13.el6uek will be installed
---> Package kernel-uek-firmware.noarch 0:4.1.12-112.14.13.el6uek will be installed
---> Package linux-firmware.noarch 0:20160616-44.git43e96a1e.0.12.el6 will be updated
---> Package linux-firmware.noarch 0:20171128-56.git17e62881.0.2.el6 will be an update
--> Finished Dependency Resolution
Dependencies Resolved
=================================================================================================
=====================================================
Package Arch Version
Repository Size
=================================================================================================
=====================================================
Installing:
kernel-uek x86_64 4.1.12-112.14.13.el6uek
ol6_UEKR4 51 M
kernel-uek-firmware noarch 4.1.12-112.14.13.el6uek
ol6_UEKR4 2.4 M
Updating:
linux-firmware noarch 20171128-56.git17e62881.0.2.el6
ol6_UEKR4 74 M
Transaction Summary
=================================================================================================
=====================================================
Install 2 Package(s)
Upgrade 1 Package(s)
(1/3): kernel-uek-4.1.12-112.14.13.el6uek.x86_64.rpm
| 51 MB 00:00
(2/3): kernel-uek-firmware-4.1.12-112.14.13.el6uek.noarch.rpm
| 2.4 MB 00:00
(3/3): linux-firmware-20171128-56.git17e62881.0.2.el6.noarch.rpm
| 74 MB 00:00
-------------------------------------------------------------------------------------------------
-----------------------------------------------------
Total
214 MB/s | 128 MB 00:00
Running rpm_check_debug
Running Transaction Test
Transaction Test Succeeded
Running Transaction
Installing : kernel-uek-firmware-4.1.12-112.14.13.el6uek.noarch
1/4
Updating : linux-firmware-20171128-56.git17e62881.0.2.el6.noarch
2/4
Installing : kernel-uek-4.1.12-112.14.13.el6uek.x86_64
3/4
Cleanup : linux-firmware-20160616-44.git43e96a1e.0.12.el6.noarch
4/4
ol6_UEKR4/filelists
| 18 MB 00:00
Uploading /boot/vmlinuz-4.1.12-112.14.13.el6uek.x86_64 to http://169.254.0.3/kernel
Uploading /boot/initramfs-4.1.12-112.14.13.el6uek.x86_64.img to http://169.254.0.3/initrd
Uploading /tmp/tmp5HjrRUcmdline to http://169.254.0.3/cmdline
Note
For information about applying Oracle database patches to a DB system, see Patching a DB
System.
Configuring a DB System
This topic provides information to help you configure your DB system.
Oracle recommends that you run a Network Time Protocol (NTP) daemon on your 1-node DB
systems to keep system clocks stable during rebooting. If you need information about an NTP
daemon, see Setting Up “NTP (Network Time Protocol) Server” in RHEL/CentOS 7.
Oracle recommends that you configure NTP on both nodes in a 2-node RAC DB system to
synchronize time across the nodes. If you do not configure NTP, then Oracle Clusterware
configures and uses the Cluster Time Synchronization Service (CTSS), and the cluster time
might be out-of-sync with applications that use NTP for time synchronization.
For information about configuring NTP on a version 12c database, see Setting Network Time
Protocol for Cluster Time Synchronization. For a version 11g database, see Network Time
Protocol Setting.
l For version 12c databases, if you don’t want your tablespaces encrypted, you can set
the ENCRYPT_NEW_TABLESPACES database initialization parameter to DDL.
l On a 1- or 2-node RAC DB system, you can use the dbcli update-tdekey command to
update the master encryption key for a database.
l You must create and activate a master encryption key for any PDBs that you create.
After creating or plugging in a new PDB on a 1- or 2-node RAC DB System, use the
dbcli update-tdekey command to create and activate a master encryption key for the
PDB. Otherwise, you might encounter the error ORA-28374: typed master key not
found in wallet when attempting to create tablespaces in the PDB. In a multitenant
environment, each PDB has its own master encryption key which is stored in a single
keystore used by all containers. For more information, see "Overview of Managing a
Multitenant Environment" in the Oracle Database Administrator’s Guide.
l For information about encryption on Exadata DB systems, see Using Tablespace
Encryption in Exadata Cloud Service.
For detailed information about database encryption, see the Oracle Database Security White
Papers.
Patching a DB System
This topic describes the procedures to patch bare metal and virtual machine DB systems and
database homes by using the Console, the API, or the database CLI (dbcli Integration Cloud).
Note
19.0.0.0 April 2020, January 2020 April 2020, January 2020, October
2019, July 2019
18.0.0.0 April 2020, January 2020 April 2020, January 2020, October
2019, July 2019
12.2.0.1 April 2020, January 2020 April 2020, January 2020, October
2019, July 2019
12.1.0.2 April 2020, January 2020 April 2020, January 2020, October
2019, July 2019
For administrators: The policy in Let database admins manage DB systems enables the
specified group to do everything with databases and related Database resources.
If you're new to policies, see Getting Started with Policies and Common Policies. Details about
writing policies for databases are located in Details for the Database Service.
Patching a DB system requires a reboot, which can take several minutes. To minimize the
impact on users, run the patch at a time when the system has the fewest users. To avoid
system interruption, consider implementing a high availability strategy such as Oracle Data
Guard. For more information, see Using Oracle Data Guard with the Database CLI.
Oracle recommends that you back up your database and test the patch on a test system
before you apply the patch. See Backing Up a Database for more information.
Always patch a DB system before you patch the databases within that system. The Console
displays the latest DB system patch and the previous patch. You can use either of these
patches, but we recommend using the latest patch when possible.
Prerequisites
DB systems require access to the Oracle Cloud Infrastructure Object Storage service,
including connectivity to the applicable Swift endpoint for Object Storage. We recommend
using a service gateway with the VCN to enable this access. For more information, see these
topics:
l Network Setup for DB Systems. This topic describes the procedure to set up your VCN
for the DB system, including the service gateway.
l https://cloud.oracle.com/infrastructure/storage/object-storage/faq. This topic explains
which Swift endpoints to use.
Important
We recommend that you use the pre-check action to ensure that your DB system or database
home has met the requirements for the patch you want to apply.
PATCHING A DB SYSTEM
To patch a DB system.
1. Open the navigation menu.Click > Database > Bare Metal, VM, and Exadata.
To patch a database
Before you perform this procedure, ensure that the latest patch was successfully applied to
the DB system.
1. Open the navigation menu. Click > Database > Bare Metal, VM, and Exadata.
2. Choose your Compartment.
A list of DB systems is displayed.
3. Find the DB system where the database is located, and click the system name to display
details about it.
A list of databases is displayed.
4. Find the database on which you want to perform the patch operation, and click its name
to display details about it.
5. Under Resources, click Patches.
6. Review the list of patches. Oracle Cloud Infrastructure displays the two most recent
patches. We recommend using the latest patch when possible.
7. Click Actions (three dots) for the patch you are interested in, and then select one of the
following actions:
l Pre-check: Check for any prerequisites to ensure that the patch can be
successfully applied.
l Apply: Performs the pre-check, and then applies the patch.
8. Confirm when prompted.
9. In the list of patches, click the patch name to display its patch request and monitor the
progress of the patch operation.
While a patch is being applied, the patch's status displays as Applying and the
database's status displays as Updating. If the operation completes successfully, the
patch's status changes to Applied and the database's status changes to Available.
Each patch history entry represents an attempted patch operation and indicates whether the
operation was successful or failed. You can retry a failed patch operation. Repeating an
operation results in a new patch history entry.
Patch history views in the Console do not show patches that were applied by using command
line tools like dbcli or the Patch utility.
3. To display details about the system you are interested in, locate the system name and
click it.
4. Under Resources, click Patch History.
The history of patch operations for that DB system is displayed.
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.
DB systems:
l ListDbSystemPatches
l ListDbSystemPatchHistoryEntries
l GetDbSystemPatch
l GetDbSystemPatchHistoryEntry
l UpdateDbSystem
Databases:
l ListDbHomePatches
l ListDbHomePatchHistoryEntries
l GetDbHomePatch
l GetDbHomePatchHistoryEntry
l UpdateDbHome
For the complete list of APIs for the Database service, see Database Service API.
This topic explains how to use the command line interface on the DB system to patch a DB
system. Patches are available from the Oracle Cloud Infrastructure Object Storage service.
You use the DBCLI commands to download and apply patches to some or all components in
your system.
PREREQUISITES
To connect to the DB system via SSH, you need the path to private key associated with the
public key used when the DB system was launched.
You also need the public or private IP address of the DB system. Use the private IP address to
connect to the DB system from your on-premises network, or from within the virtual cloud
network (VCN). This includes connecting from a host located on-premises connecting through
a VPN or FastConnect to your VCN, or from another host in the same VCN. Use the
DB System's public IP address to connect to the system from outside the cloud (with no VPN).
You can find the IP addresses in the Oracle Cloud Infrastructure Console on the DB System
Details page by clicking Nodes under the Resources list. The values are displayed in the
Public IP Address and Private IP Address & DNS Name columns of the Nodes table.
2. Log in as opc and then sudo to the root user. Use sudo su - with a hyphen to invoke the
root user's profile, which will set the PATH to the dbcli directory
(/opt/oracle/dcs/bin).
login as: opc
4. Wait for the update job to complete successfully. Check the status of the job by using
the dbcli list-jobs command.
[root@dbsys ~]# dbcli list-jobs
2. Log in as opc and then sudo to the root user. Use sudo su - with a hyphen to invoke the
root user's profile, which will set the PATH to the dbcli directory
(/opt/oracle/dcs/bin).
login as: opc
3. Display the installed patch versions by using the dbcli describe-component command. If
the Available Version column indicates a version number for a component, you should
update the component.
[root@dbsys ~]# dbcli describe-component
System Version
---------------
12.1.2.10.0
4. Display the latest patch versions available in Object Storage by using the dbcli describe-
latestpatch command.
[root@dbsys ~]# dbcli describe-latestpatch
componentType availableVersion
--------------- --------------------
gi 12.1.0.2.161018
db 11.2.0.4.161018
db 12.1.0.2.161018
oak 12.1.2.10.0
2. Log in as opc and then sudo to the root user. Use sudo su - with a hyphen to invoke the
root user's profile, which will set the PATH to the dbcli directory
(/opt/oracle/dcs/bin).
login as: opc
Job details
----------------------------------------------------------------
ID: 9a02d111-e902-4e94-bc6b-9b820ddf6ed8
Description: Server Patching
Status: Running
Created: January 19, 2017 9:37:11 AM PST
Message:
5. Verify that the server components were updated successfully by using the dbcli
describe-component command. The Available Version column should indicate
update-to-date.
2. Log in as opc and then sudo to the root user. Use sudo su - with a hyphen to invoke the
root user's profile, which will set the PATH to the dbcli directory
(/opt/oracle/dcs/bin).
3. Get the ID of the database home by using the dbcli list-dbhomes command.
[root@dbsys ~]# dbcli list-dbhomes
ID Name DB Version Home Location
------------------------------------ ----------------- ---------- ------------------------------
------------
b727bf80-c99e-4846-ac1f-28a81a725df6 OraDB12102_home1 12.1.0.2
/u01/app/orauser/product/12.1.0.2/dbhome_1
4. Update the database home components by using the dbcli update-dbhome command
and providing the ID from the previous step.
[root@dbsys ~]# dbcli update-dbhome -i b727bf80-c99e-4846-ac1f-28a81a725df6
{
"jobId" : "31b38f67-f993-4f2e-b7eb-5bccda9901ae",
"status" : "Created",
"message" : null,
"reports" : [ ],
"createTimestamp" : "January 20, 2017 10:08:48 AM PST",
"resourceList" : [ ],
"description" : "DB Home Patching: Home Id is 52e2e799-946a-4339-964b-c203dee35328",
"updatedTime" : "January 20, 2017 10:08:48 AM PST"
}
Job details
----------------------------------------------------------------
ID: 31b38f67-f993-4f2e-b7eb-5bccda9901ae
Description: DB Home Patching: Home Id is b727bf80-c99e-4846-ac1f-28a81a725df6
Status: Success
Created: January 20, 2017 10:08:48 AM PST
Message:
Status
---------------------------------------- ----------------------------------- --------------------
--------------- ----------
Create Patching Repository Directories January 20, 2017 10:08:49 AM PST January 20, 2017
10:08:49 AM PST Success
Download latest patch metadata January 20, 2017 10:08:49 AM PST January 20, 2017
10:08:49 AM PST Success
Update System version January 20, 2017 10:08:49 AM PST January 20, 2017
10:08:49 AM PST Success
Update Patching Repository January 20, 2017 10:08:49 AM PST January 20, 2017
10:08:58 AM PST Success
Opatch updation January 20, 2017 10:08:58 AM PST January 20, 2017
10:08:58 AM PST Success
Patch conflict check January 20, 2017 10:08:58 AM PST January 20, 2017
10:12:00 AM PST Success
db upgrade January 20, 2017 10:12:00 AM PST January 20, 2017
10:22:17 AM PST Success
6. Verify that the database home components were updated successfully by using the dbcli
describe-component command. The Available Version column should indicate
update-to-date.
Note
To apply an interim patch (previously known as a "one-off" patch) to fix a specific defect,
follow the procedure in this section. Use the Opatch utility to apply an interim patch to a
database home.
5. Set the Oracle home environment variable to point to the target Oracle home.
sudo su - oracle
export ORACLE_HOME=/u02/app/oracle/product/12.1.0.2/dbhome_1
6. Change to the directory where you placed the patch, and unzip the patch.
cd <work_dir_where_opatch_is stored>
unzip p26543344_122010_Linux-x86-64.zip
7. Change to the directory with the unzipped patch, and check for conflicts.
cd 26543344
$ORACLE_HOME/OPatch/opatch prereq CheckConflictAgainstOHWithDetail -ph ./
11. If the readme indicates that the patch has a sqlpatch component, run the datapatch
command against each database.
Before you run datapatch, ensure that all pluggable databases (PDBs) are open. To open
a PDB, you can use SQL*Plus to execute ALTER PLUGGABLE DATABASE <pdb_name>
OPEN READ WRITE; against the PDB.
$ORACLE_HOME/OPatch/datapatch
Creating a Database
Note
When you launch a bare metal DB system, an initial database is created in that system. You
can create additional databases in that DB system at any time by using the Console or the API.
The database edition will be the edition of the DB system in which the database is created, and
each new database is created in a separate database home. You can create an empty
database or reproduce a database by using a backup.
When creating a new database using a backup stored in Object Storage as the source, you
have the following backup source options:
l Daily automatic backup. Requires that you have automatic backups enabled and an
available backup to use. If you are creating a database from an automatic backup, you
can choose any level 0 weekly backup, or a level 1 incremental backup created after the
most recent level 0 backup. For more information on automatic backups, see Automatic
Incremental and Archived Redo Log Backups.
l On-demand full backup. See To create an on-demand full backup of a database for
information on creating an on-demand backup.
For information on configuring your DB system to back up to Object Storage, see Backing Up a
Database to Oracle Cloud Infrastructure Object Storage.
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: The policy in Let database admins manage DB systems lets the specified
group do everything with databases and related Database resources.
If you're new to policies, see Getting Started with Policies and Common Policies. If you want
to dig deeper into writing policies for databases, see Details for the Database Service.
Note
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
A list of DB systems is displayed.
3. In the list of DB systems, find the DB system in which you want to create the database,
and then click its name to display details about it.
4. Click Create Database.
5. In the Create Database dialog, enter the following:
l Database name: The name for the database. The database name must begin
with an alphabetic character and can contain a maximum of eight alphanumeric
characters. Special characters are not permitted.
l Database version: The version of the database. You can mix database versions
on the DB system, but not editions.
l PDB name (Optional) For version 12.1.0.2 and later, you can specify the name of
the pluggable database. The PDB name must begin with an alphabetic character,
When the database creation is complete, the status changes from Provisioning to Available.
l When you create a database from a backup, you can choose a different DB system and
compartment. However, the availability domain will be the same as where the source
database is hosted.
Tip
l The DB system you specify must support the same type as the system from which the
backup was taken. For example, if the backup is from a single-node database, then the
target DB system must be a single-node shape.
l The version of the target DB system must be the same or higher than the version of the
backup.
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
A list of DB systems is displayed.
3. Navigate to the backup or standalone backup you want to use to create the new DB
system:
Tip
To select the last archived redo log automatic backup as the source
a. Find the DB system where the database is located, and click the system name to
display details about it.
b. Find the database associated with the backup you wish to use, and click its name
to display details about it.
c. On the database details page, click Create Database from Last Backup.
d. In the Create Database from Backup dialog, select Create database from
last backup.
d. In the Create Database from Backup dialog, select Create database from
specified timestamp.
Note
l Database Name: The name for the database. The database name must begin
with an alphabetic character and can contain a maximum of eight alphanumeric
characters. Special characters are not permitted.
l Database Admin Password: A strong password for SYS, SYSTEM, TDE wallet,
and PDB Admin. The password must be 9 to 30 characters and contain at least two
uppercase, two lowercase, two numeric, and two special characters. The special
characters must be _, #, or -. The password must not contain the username (SYS,
SYSTEM, and so on) or the word "oracle" either in forward or reversed order and
regardless of casing.
l Confirm Database Admin Password: Re-enter the Database Admin Password
you specified.
l Password for Transparent Data Encryption (TDE) Wallet or RMAN
Encryption:
Enter either the TDE wallet password or the RMAN encryption password for the
backup, whichever is applicable. The TDE wallet password is the SYS password
provided when the database was created by using the Oracle Cloud Infrastructure
Console, API, or CLI. The RMAN encryption password is typically required instead
if the password was subsequently changed manually.
5. Click Create Database.
To terminate a database
You'll get the chance to back up the database prior to terminating it. This creates a standalone
backup that can be used to create a database later. Oracle recommends that you create this
final backup for any production (non-test) database.
Note
You cannot terminate a database that is assuming the primary role in a Data Guard
association. To terminate it, you can switch it over to the standby role.
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
A list of DB systems is displayed.
3. In the list of DB systems, find the DB system that contains the database you want to
terminate, and then click its name to display details about it.
4. In the list of databases, find the database you want to terminate, and then click its
name to display details about it.
5. Click Actions, and then click Terminate.
6. In the confirmation dialog, indicate whether you want to back up the database before
terminating it, and type the name of the database to confirm the termination.
7. Click Terminate Database.
The database's status indicates Terminating.
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.
Database homes:
l ListDbHomes
l GetDbHome
l CreateDbHome
l DeleteDbHome
Databases:
l ListDatabases
l GetDatabase
For the complete list of APIs for the Database service, see Database Service API.
Monitoring a Database
This topic explains how to set up an:
Each console is a web-based database management tool inside the Oracle database. You can
use the console to perform basic administrative tasks such as managing user security,
memory, and storage, and view performance information.
Some of the procedures below require permission to create or update security lists. For more
information about security list policies, see Security Lists.
You must also update the security list and iptables for the DB system as described later in this
topic.
When you enable the console, you'll set the port for the console. The procedure below uses
port 5500, but each additional console enabled on the same DB system will have a different
port.
sudo su - oracle
. oraenv
<provide the database SID at the prompt>
sqlplus / as sysdba
For example:
SQL> exec DBMS_XDB_CONFIG.SETHTTPSPORT(5500);
l To determine the port for a previously enabled console, use the following
command.
select dbms_xdb_config.getHttpsPort() from dual;
For example:
SQL> select dbms_xdb_config.getHttpsPort() from dual;
DBMS_XDB_CONFIG.GETHTTPSPORT()
------------------------------
5500
3. Return to the operating system by typing exit and then confirm that the listener is
listening on the port:
lsnrctl status | grep HTTP
(DESCRIPTION=(ADDRESS=(PROTOCOL=tcps)(HOST=xxx.us.oracle.com)(PORT=5500))(Security=(my_wallet_
directory=/u01/app/oracle/admin/prod/xdb_wallet))(Presentation=HTTP)(Session=RAW))
4. If you're using a 2-node RAC DB system, see To set the required permissions on a 2-
node RAC DB system.
5. Open the console's port as described in Opening Ports on the DB System.
6. Update the security list for the console's port as described in Updating the Security List
for the DB System.
1. SSH to one of the nodes in the DB system, log in as opc, sudo to the grid user.
[opc@dbsysHost1 ~]$ sudo su - grid
[grid@dbsysHost1 ~]$ . oraenv
ORACLE_SID = [+ASM1] ?
The Oracle base has been set to /u01/app/grid
2. Get the location of the wallet directory, shown in red below in the command output.
[grid@dbsysHost1 ~]$ lsnrctl status | grep xdb_wallet
(DESCRIPTION=(ADDRESS=(PROTOCOL=tcps)(HOST=dbsysHost1.sub04061528182.dbsysapril6.oraclevcn.com)
(PORT=5500))(Security=(my_wallet_directory=/u01/app/oracle/admin/dbsys12_phx3wm/xdb_wallet))
(Presentation=HTTP)(Session=RAW))
3. Return to the opc user, switch to the oracle user, and change to the wallet directory.
[opc@dbsysHost1 ~]$ sudo su - oracle
[oracle@dbsysHost1 ~]$ cd /u01/app/oracle/admin/dbsys12_phx3wm/xdb_wallet
7. Important! Repeat the steps above on the other node in the cluster.
1. From a web browser, connect to the console using the following URL format:
https://<ip_address>:<port>/em
To learn more about EM Express, see Introduction to Oracle Enterprise Manager Database
Express.
Note
By default, the Enterprise Manager Database Control console is not enabled on version
11.2.0.4 databases. You can enable the console:
l when you create a database by using the dbcli create-database with the -co parameter
l for an existing database as described here.
Port 1158 is the default port used for the first console enabled on the DB system, but each
additional console enabled on the DB system will have a different port.
Note
To determine the port for the Enterprise Manager Database Control console
1. SSH to the DB system, log in as opc, and sudo to the oracle user.
sudo su - oracle
. oraenv
<provide the database SID at the prompt>
1. From a web browser, connect to the console using the following URL format:
https://<ip_address>:<port>/em
To learn more about Enterprise Manager Database Control, see Introduction to Oracle
Enterprise Manager Database Control.
You'll create SSH keys on each node and copy the key to the other node, so that each node
has the keys for both nodes. The following procedure uses the sample names node1 and
node2.
2. Create a directory called .ssh, set its permissions, create an RSA key, and add the
public key to the authorized_keys file.
mkdir .ssh
chmod 755 .ssh
ssh-keygen -t rsa
cat id_rsa.pub > authorized_keys
2. On node1, run Enterprise Manager Configuration Assistant (EMCA) using the emca.rsp
file as input.
$ORACLE_HOME/bin/emca -config dbcontrol db -repos create -cluster -silent -respFile <location of
response file above>
3. On node2, configure the console so the agent in node1 reports to the console in node1,
and the agent in node2 reports to the console in node2.
$ORACLE_HOME/bin/emca -reconfig dbcontrol -silent -cluster -EM_NODE <node2 host> -EM_NODE_LIST
<node2 host> -DB_UNIQUE_NAME <db_unique_name>
-SERVICE_NAME <db_unique_name>.<db_domain>
1. On each node, edit iptables to open the console's port as described in Opening Ports on
the DB System.
2. Update the security list for the console's port as described in Updating the Security List
for the DB System.
l 1158 - For Enterprise Manager Database Control. 1158 is the default port, but each
additional console enabled on the DB system will have a different port. If you're not
sure which port to open for a particular console, see Monitoring a Database with
Enterprise Manager Database Control.
For important information about critical firewall rules, see Essential Firewall Rules.
(If necessary, you can restore the original file by using the command iptables-
restore < /tmp/iptables.orig.)
4. Dynamically add a rule to iptables to allow inbound traffic on the console port, as shown
in the following sample. Change the port number and comment as needed.
[root@dbsys ~]# iptables -I INPUT 8 -p tcp -m state --state NEW -m tcp --dport 5500 -j ACCEPT -m
comment --comment "Required for EM Express.”
The change takes effect immediately and will remain in effect when the node is
rebooted.
7. Update the DB system's security list as described in Updating the Security List for the
DB System.
Review the list of ports in Opening Ports on the DB System and for every port you open in
iptables, update the security list used for the DB system, or create a new security list.
Note that port 1521 for the Oracle default listener is included in iptables, but should also be
added to the security list.
For detailed information about creating or updating a security list, see Security Lists.
Backing Up a Database
Backing up your DB System is a key aspect of any Oracle database environment. You can
store backups in the cloud or in local storage. Each backup destination has advantages,
disadvantages, and requirements that you should consider, as described below.
Local Storage
l Backups are stored locally in the Fast Recovery Area of the DB System.
l Durability: Low
l Availability: Medium
l Back Up and Recovery Rate: High
l Advantages: Optimized back up and fast point-in-time recovery.
l Disadvantages: If the DB System becomes unavailable, the backup is also unavailable.
Currently, Oracle Cloud Infrastructure does not provide the ability to attach block storage
volumes to a DB System, so you cannot back up to network attached volumes.
Note
This topic explains how to work with backups managed by Oracle Cloud Infrastructure. You do
this by using the Console or the API. (For unmanaged backups, you can use RMAN or dbcli,
and you must create and manage your own Object Storage buckets for backups. See Backing
Up a Database to Object Storage Using RMAN.)
Warning
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.
If you're new to policies, see Getting Started with Policies and Common Policies.
PREREQUISITES
The DB system requires access to the Oracle Cloud Infrastructure Object Storage service,
including connectivity to the applicable Swift endpoint for Object Storage. Oracle recommends
using a service gateway with the VCN to enable this access. For more information, see these
topics:
l Network Setup for DB Systems: For information about setting up your VCN for the DB
system, including the service gateway.
l https://cloud.oracle.com/infrastructure/storage/object-storage/faq: For information
about the Swift endpoints to use.
Important
The following information applies to managed backups configured using the Oracle Cloud
Infrastructure Console or API.
When you enable the Automatic Backup feature for a database, the service creates the
following on an on-going basis:
l Weekly level 0 backup, generally created on a specified weekend day. A level 0 backup
is the equivalent of a full backup. Note that in the Console, weekly level 0 backups
appear in the list of backups with backup type "incremental", as do the daily level 1
backups.
l Daily level 1 backups, which are incremental backups created on each day for the six
days following the level 0 backup day.
Level 0 and level 1 backups are stored in Object Storage and have an assigned OCID.
l Ongoing archived redo log backups (with a minimum frequency of every 60 minutes).
The Last Backup Time field on the database details page in the Oracle Cloud
Infrastructure Console displays the time of the last archived redo logs. This backup
differs from the level 0 and level 1 automatic backups in that it is based on log data and
does not have an assigned OCID. The last archived redo log backup can be used to
create a new database or to recover a database with minimal data loss.
The automatic backup process used to create level 0 and level 1 backups can run at any time
within the daily backup window (between midnight and 6:00 AM). See note for backup window
time zone information. Automatic incremental backups (level 0 and level 1) are retained in
Object Storage for 30 days by default.
Backup Retention
If you choose to enable automatic backups, you can choose one of the following preset
retention periods: 7 days, 15 days, 30 days, 45 days, or 60 days. The system automatically
deletes your incremental backups at the end of your chosen retention period.
Audit and Trace File Retention for Databases Using Automatic Backups
Oracle Database writes audit and trace files to your database's local storage in the /u01
directory. These files are retained for 30 days by default, though you can change this interval.
Once a day, audit and trace files older than 30 days (or the user-specified interval, if
applicable) are discarded by a Oracle Scheduler job. You can also disable the Scheduler job if
you want to retain these files permanently. Use the following dbcli commands to make
changes to this Scheduler job.
For example:
dbcli update-database -in inventorydb -lr 15
l To disable the daily discard Scheduler job for older audit and trace files:
dbcli update-schedule -i <schedulerID> -d
For example:
dbcli update-schedule -i 5678 -d
Backup Scheduling
The automatic backup process starts at any time during your daily backup window. You can
optionally specify a 2-hour scheduling window for your database during which the automatic
backup process will begin. There are 12 scheduling windows to choose from, each starting on
an even-numbered hour (for example, one window runs from 4:00-6:00 AM, and the next
from 6:00-8:00 AM). Backups jobs do not necessarily complete within the scheduling window
The default backup window of 00:00 to 06:00 in the time zone of the DB system's region is
assigned to your database if you do not specify a window. Note that the default backup
scheduling window is six hours long, while the windows you specify are two hours long. See
note for backup window time zone information.
Note
You can create a full backup of your database at any time unless your database is assuming
the standby role in a Data Guard association.
STANDALONE BACKUPS
When you terminate a DB system or a database, all of its resources are deleted, along with
any automatic backups. Full backups remain in Object Storage as standalone backups. You
can use a standalone backup to create a new database.
You can use the Console to enable automatic incremental backups, create full backups on
demand, and view the list of managed backups for a database. The Console also allows you to
delete full backups.
Note
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
A list of DB systems is displayed.
3. Find the DB system where the database is located, and click the system name to display
details about it.
A list of databases is displayed.
4. Find the database for which you want to enable or disable automatic backups, and click
its name to display database details. The details indicate whether automatic backups
are enabled. When backups are enabled, the details also indicate the chosen backup
retention period .
5. Click Configure Automatic Backups.
6. In the Configure Automatic Backups dialog, check or uncheck Enable Automatic
Backup, as applicable.
If you are enabling automatic backups, you can choose to configure the following:
l Backup Retention Period: If you enable automatic backups, you can choose
one of the following preset retention periods: 7 days, 15 days, 30 days, 45 days,
60 days, or 90 days. The default selection is 30 days.
l Backup Scheduling: If you enable automatic backups, you can choose a two-
hour scheduling window to control when backup operations begin. If you do not
specify a window, the six-hour default window of 00:00 to 06:00 (in the time zone
of the DB system's region) is used for your database. See Backup Scheduling for
more information.
7. Click Save Changes.
3. Find the DB system where the database is located, and click the system name to display
details about it.
A list of databases is displayed.
4. Find the database for which you want to create an on-demand full backup and click its
name to display database details.
5. Under Resources, click Backups.
A list of backups is displayed.
6. Click Create Backup.
Note
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
A list of DB systems is displayed.
3. Find the DB system where the database is located and click the DB system name to
display details.
A list of databases is displayed.
4. Find the database you are interested in and click its name to display database details.
5. Under Resources, click Backups.
A list of backups is displayed.
6. Click the Actions icon (three dots) for the backup you are interested in, and then click
Delete.
7. Confirm when prompted.
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.
l ListBackups
l GetBackup
l CreateBackup
l DeleteBackup
l UpdateDatabase - To enable and disable automatic backups.
For the complete list of APIs for the Database service, see Database Service API.
WH AT'S NEXT?
See Recovering a Database from Object Storage for information on restoring your database.
See To create a database from a backup in an existing DB system for information on creating
a new database from a backup. You have the choice of using a daily incremental backup, a
standalone backup, the latest archive redo log backup, or a timestamp for a point-in-time
copy.
See To create a DB system from a backup for information on creating a new DB system using
a backup as the source for the initial database. You have the choice of using a daily
incremental backup, a standalone backup, the latest archive redo log backup, or a timestamp
for a point-in-time copy.
Note
This topic explains how to use Recovery Manager (RMAN) to manage backups of your Bare
Metal or Virtual Machine DB system database to your own Object Storage. For backups
managed by Oracle Cloud Infrastructure, see Backing Up a Database to Oracle Cloud
Infrastructure Object Storage.
To back up to the service you'll need to create an Object Storage bucket for the backups,
generate a password for the service, install the Oracle Database Cloud Backup Module, and
then configure RMAN to send backups to the service. The backup module is a system backup
to tape (SBT) interface that’s tightly integrated with RMAN, so you can use familiar
RMAN commands to perform backup and recovery operations.
You'll notice Swift mentioned in the Console and in the endpoint URL for the service. That's
because the backup module is typically used to back up to the Oracle Database Backup Cloud
Service, which is an OpenStack Swift object store.
Tip
PREREQUISITES
l A DB system and a database to back up. For more information, see Creating Bare Metal
and Virtual Machine DB Systems.
l The DB system's cloud network (VCN) must be configured with access to Object
Storage:
o For Object Storage access in the same region as the DB system: Oracle
recommends using a service gateway. For more information, see Service
Gateway for the VCN.
o For Object Storage access in a different region than the DB system: Use an
internet gateway. Note that the network traffic between the DB system and Object
Storage does not leave the cloud and never reaches the public internet. For more
information, see Internet Gateway.
l An existing Object Storage bucket to use as the backup destination. You can use the
Console or the Object Storage API to create the bucket. For more information, see
Managing Buckets.
l An auth token generated by Oracle Cloud Infrastructure. You can use the Console or the
IAM API to generate the password. For more information, see Working with Auth
Tokens.
l The user name (specified when you install and use the backup module) must have
tenancy-level access to Object Storage. An easy way to do this is to add the user name
to the Administrators group. However, that allows access to all of the cloud services.
Instead, an administrator should create a policy like the following that limits access to
only the required resources in Object Storage for backing up and restoring the
database:
Allow group <group_name> to manage objects in compartment <compartment_name> where
target.bucket.name = '<bucket_name>'
For more information about adding a user to a group, see Managing Groups. For more
information about policies, see Getting Started with Policies.
1. SSH to the DB system, log in as opc, and sudo to the oracle user.
ssh -i <SSH_key_used_when_launching_the_DB_system> opc@<DB_system_IP_address_or_hostname>
login as: opc
sudo su - oracle
2. Change to the directory that contains the backup module opc_install.jar file.
cd /opt/oracle/oak/pkgrepos/oss/odbcs
Parameter Description
-opcId The user name for the Oracle Cloud Infrastructure user account, for
example:
-opcId <username>@<example>.com
This is the user name you use to sign in to the Console.
The user name must be a member of the Administrators group, as
described in Prerequisites.
You can also specify the user name in single quotes. This might be
necessary if the name contains special characters, for example:
-opcId 'j~smith@<example>.com'
Make sure to use straight single quotes and not slanted apostrophes.
-opcPass The auth token generated by using the Console or IAM API, in single
quotes, for example:
-opcPass '<password>'
Make sure to use straight single quotes and not slanted apostrophes.
For more information, see Managing User Credentials.
This is not the password for the Oracle Cloud Infrastructure user.
-container The name of an existing bucket in Object Storage to use as the backup
destination, for example:
-container DBBackups
-walletDir The directory where the install tool will create an Oracle Wallet
containing the Oracle Cloud Infrastructure user name and auth token.
-walletDir ~/hsbtwallet creates the wallet in the current user
(oracle) home directory.
Parameter Description
-libDir The directory where the SBT library is stored. The directory must
already exist before you run the command. This parameter causes the
latest SBT library to be downloaded.
-libDir ~/lib/ downloads the libopc.so file to the current user's
home directory, for example, /home/oracle/lib/libopc.so.
-configfile The name of the initialization parameter file that will be created by the
install tool. This file will be referenced by your RMAN jobs.
-configfile ~/config creates the file in the current user's home
directory, for example, /home/oracle/config.
CONFIGURING RMAN
This section describes how to configure RMAN to use the bucket as the default backup
destination. The following assumes you are still logged in to the DB system.
1. On the DB system, set the ORACLE_HOME and ORACLE_SID environment variables using
the oraenv utility.
. oraenv
3. Configure RMAN to use the SBT device and point to the config file that was created
when you installed the backup module. A sample command for a version 12 database is
shown here.
RMAN> CONFIGURE CHANNEL DEVICE TYPE 'SBT_TAPE' PARMS 'SBT_LIBRARY=/home/oracle/lib/libopc.so,
SBT_PARMS=(OPC_PFILE=/home/oracle/config)';
4. Configure RMAN to use SBT_TAPE by default. The following sample enables the
controlfile and spfile autobackup to SBT_TAPE and configures encryption
(recommended). There are other settings that may apply to your installation such as
compression, number of backup and recovery channels to use, backup retention policy,
archived log deletion policy, and more. See the Oracle Backup and Recovery
documentation for your version of Oracle for more information on choosing the
appropriate settings.
RMAN> CONFIGURE DEFAULT DEVICE TYPE TO SBT_TAPE;
RMAN> CONFIGURE BACKUP OPTIMIZATION ON;
RMAN> CONFIGURE CONTROLFILE AUTOBACKUP ON;
RMAN> CONFIGURE CONTROLFILE AUTOBACKUP FORMAT FOR DEVICE TYPE SBT_TAPE TO '%F';
RMAN> CONFIGURE ENCRYPTION FOR DATABASE ON;
Once the RMAN configuration is complete, you can use the same RMAN commands that you
regularly use for tape backups.
Note that this setting is not permanent; you must set it for each new RMAN session.
2. Back up the database and archivelogs. Below are some example commands. See the
Oracle Backup and Recovery documentation for your version of Oracle for more
information about choosing a back up procedure that meets your needs. Be sure to back
up regularly to minimize potential data loss and always include a copy of the spfile and
controlfile. Note that the example below uses multi-section incremental backups, which
is a feature introduced in 12c. When using 11g, omit the section size clause.
RMAN> BACKUP INCREMENTAL LEVEL 0 SECTION SIZE 512M DATABASE PLUS ARCHIVELOG;
RMAN> BACKUP INCREMENTAL LEVEL 1 SECTION SIZE 512M DATABASE PLUS ARCHIVELOG;
RMAN> BACKUP INCREMENTAL LEVEL 1 CUMULATIVE SECTION SIZE 512M DATABASE PLUS ARCHIVELOG;
3. Backup archivelogs frequently to minimize potential data loss, and keep multiple
backup copies as a precaution.
RMAN> BACKUP ARCHIVELOG ALL NOT BACKED UP 2 TIMES;
When the backup job completes, you can display the backup files in your bucket in the Console
on the Storage page, by selecting Object Storage.
WH AT'S NEXT?
Note
This topic explains how to back up to the local Fast Recovery Area on a bare metal DB system
by using the database CLI (dbcli). Some sample dbcli commands are provided below. For
complete command syntax, see the Oracle Database CLI Reference.
Note
You'll use the dbcli commands to create a backup configuration, associate the backup
configuration with the database, initiate the backup operation, and then review the backup
job.
2. Log in as opc and then sudo to the root user. Use sudo su - with a hyphen to invoke the
root user's profile, which will set the PATH to the dbcli directory
(/opt/oracle/dcs/bin).
login as: opc
"message" : null,
"reports" : [ {
"taskId" : "TaskParallel_471",
"taskName" : "persisting backup config metadata",
"taskResult" : "Success",
"startTime" : 1467774813141,
"endTime" : 1467774813207,
"status" : "Success",
"taskDescription" : null,
"parentTaskId" : "TaskSequential_467",
"jobId" : "e7050756-0d83-48ce-9336-86592be59827",
"reportLevel" : "Info",
"updatedTime" : 1467774813207
} ],
"createTimestamp" : 1467774781851,
"description" : "create backup config:prodbackup",
"updatedTime" : 1467774813236
}
The example above uses full parameter names for demonstration purposes, but you can
abbreviate the parameters like this:
dbcli create-backupconfig -n prodbackup -d disk -w 5
4. Get the ID of the database you want to back up by using the dbcli list-databases
command.
[root@dbsys ~]# dbcli list-databases
5. Get the ID of the backup configuration by using the dbcli list-backupconfigs command.
[root@dbbackup backup]# /opt/oracle/dcs/bin/dbcli list-backupconfigs
ID Name DiskRecoveryWindow
BackupDestination createTime
---------------------------------------- -------------------- ----- ------ ----------------------
-------------
6. Associate the backup configuration ID with the database ID by using the dbcli update-
database command.
[root@dbsys ~]# dbcli update-database --backupconfigid 78a2a5f0-72b1-448f-bd86-cf41b30b64ee --
dbid 71ec8335-113a-46e3-b81f-235f4d1b6fde
{
"jobId" : "2b104028-a0a4-4855-b32a-b97a37f5f9c5",
"status" : "Created",
"message" : null,
"reports" : [ ],
"createTimestamp" : 1467775842977,
"description" : "update database id:71ec8335-113a-46e3-b81f-235f4d1b6fde",
"updatedTime" : 1467775842978
}
You can view details about the update job by using the dbcli describe-job command and
specifying the job ID from the dbcli update-database command output, for example:
dbcli describe-job --jobid 2b104028-a0a4-4855-b32a-b97a37f5f9c5
7. Initiate the database backup by using the dbcli create-backup command. The backup
operation is performed immediately.
The following example creates a backup of the specified database.
[root@dbsys ~]# dbcli create-backup --dbid 71ec8335-113a-46e3-b81f-235f4d1b6fde
{
"createTimestamp": 1467792576854,
"description": "Backup service creation with db name: prod",
"jobId": "d6c9edaa-fc80-40a9-bcdd-056430cdc56c",
"message": null,
"reports": [],
"status": "Created",
"updatedTime": 1467792576855
}
You can view details about the back up job by using the dbcli describe-job command and
specifying the job ID from the dbcli create-backup command output, for example:
dbcli describe-job --jobid d6c9edaa-fc80-40a9-bcdd-056430cdc56c
After the backup command completes, the database backup files are available in the Fast
Recovery Area on the DB system.
WH AT'S NEXT?
Recovering a Database
For information on restoring a database on a bare metal or virtual machine DB system, see
the following topics:
Note
This topic explains how to recover a database from a backup stored in Object Storage. The
service is a secure, scalable, on-demand storage solution in Oracle Cloud Infrastructure. For
You can recover a database using the Console, API, or by using RMAN.
Warning
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.
If you're new to policies, see Getting Started with Policies and Common Policies.
PREREQUISITES
The DB system requires access to the Oracle Cloud Infrastructure Object Storage service,
including connectivity to the applicable Swift endpoint for Object Storage. Oracle recommends
using a service gateway with the VCN to enable this access. For more information, see these
topics:
l Network Setup for DB Systems: For information about setting up your VCN for the DB
system, including the service gateway.
l https://cloud.oracle.com/infrastructure/storage/object-storage/faq: For information
about the Swift endpoints to use.
You can use the Console to restore the database from a backup in the Object Storage that was
created by using the Console or the API. You can restore to the last known good state of the
database, or you can specify a point in time or an existing System Change Number (SCN). You
can also create a new database by using a standalone backup.
Note
To restore a database
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose your Compartment.
A list of DB systems is displayed.
3. Find the DB system where the database is located, and click the system name to display
details about it.
A list of databases is displayed.
4. Find the database you want to restore, and click its name to display details about it.
A list of backups is displayed in the default view of the database details. You can also
access the list of backups for a database by clicking on Backups under Resources.
5. Click Restore.
6. Select one of the following options, and then click Restore Database:
l Restore to the latest: Restores the database to the last known good state with
the least possible data loss.
l Restore to the timestamp: Restores the database to the timestamp specified.
l Restore to System Change Number (SCN): Restores the database using the
SCN specified. This SCN must be valid.
Tip
5. Click Restore.
6. In the Restore Database dialog, select Restore to the latest, Restore to
timestamp, or Restore to System Change Number (SCN). Specify a timestamp or
System Change Number if you are using an option that requires either.
7. Click Restore Database.
You can use a backup to create a database in an existing DB system or to launch a new DB
system. See the following procedures for more information:
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.
l ListBackups
l GetBackup
l RestoreDatabase
l CreateDbHome - For creating a DB system database from a standalone backup.
For the complete list of APIs for the Database service, see Database Service API.
This topic explains how to recover a Recovery Manager (RMAN) backup stored in Object
Storage.
PREREQUISITES
l A new DB system to restore the database to (see assumptions below). For more
information, see Creating Bare Metal and Virtual Machine DB Systems.
l The Oracle Database Cloud Backup Module must be installed on the DB system. For
more information, see Installing the Backup Module on the DB System.
ASSUMPTIONS
l A new DB system has been created to host the restored database and no other database
exists on the new DB system. It is possible to restore to a DB system that has existing
databases, but that is beyond the scope of this topic.
l The original database is lost and all that remains is the latest RMAN backup. For virtual
machine DB systems, the procedure assumes the DB system (inclusive of the
database) no longer exists.
Warning
l The Oracle Wallet and/or encryption keys used by the original database at the time of
the last backup is available.
l The RMAN backup contains a copy of the control file and spfile as of the most recent
backup as well as all of the datafile and archivelog backups needed to perform a
complete database recovery.
l An RMAN catalog will not be used during the restore.
2. Log in as opc and then sudo to the root user. Use sudo su - with a hyphen to invoke the
root user's profile, which will set the PATH to the dbcli directory
(/opt/oracle/dcs/bin).
login as: opc
3. You can use an existing empty database home or create a new one for the restore. Use
the applicable commands to help you complete this step.
If you will be using an existing database home:
l Use the dbcli list-dbhomes command to list the database homes.
[root@dbsys ~]# dbcli list-dbhomes
ID Name DB Version Home Location
---------------------------------------- -------------------- ---------- -----------------
----------------------------
2e743050-b41d-4283-988f-f33d7b082bda OraDB12102_home1 12.1.0.2
/u01/app/oracle/product/12.1.0.2/dbhome_1
l Use the dbcli list-databases command to ensure the database home is not
associated with any database.
If necessary, use the dbcli create-dbhome command to create a database home for the
restore.
4. Use the dbcli create-dbstorage to set up directories for DATA, RECO, and REDO storage.
The following example creates 10GB of ACFS storage for the rectest database.
[root@dbsys ~]# dbcli create-dbstorage --dbname rectest --dataSize 10 --dbstorage ACFS
Note
1. SSH to the DB system, log in as opc, and then become the oracle user.
sudo su - oracle
2. Create an entry in /etc/oratab for the database. Use the same SID as the original
database.
db1:/u01/app/oracle/product/12.1.0.2/dbhome_1:N
3. Set the ORACLE_HOME and ORACLE_SID environment variables using the oraenv utility.
. oraenv
4. Obtain the DBID of the original database. This can be obtained from the file name of the
controlfile autobackup on the backup media. The file name will include a string that
contains the DBID. The typical format of the string is c-DDDDDDDDDDDD-YYYYMMDD-NN
where DDDDDDDDDDDD is the DBID, YYYYMMDD is the date the backup was created, and NN
is a sequence number to make the file name unique. The DBID in the following
examples is 1508405000. Your DBID will be different.
Use the following curl syntax to perform a general query of Object Storage. The
parameters in red are the same parameters you specified when installing the backup
module as described in Installing the Backup Module on the DB System.
curl -u '<user_ID>.com:<auth_token>' -v https://swiftobjectstorage.<region_
name>.oraclecloud.com/v1/<object_storage_namespace>
To get the DBID from the control file name, use the following syntax:
curl -u '<user_id>.com:<auth_token>' -v https://swiftobjectstorage.<region_
name>.oraclecloud.com/v1/<object_storage_namespace>/<bucket_name>?prefix=sbt_catalog/c-
For example:
5. Run RMAN and connect to the target database. There is no need to create a pfile or
spfile or use a backup controlfile. These will be restored in the following steps.
Note that the target database is (not started). This is normal and expected at this
point.
rman target /
Copyright (c) 1982, 2014, Oracle and/or its affiliates. All rights reserved.
7. Run the STARTUP NOMOUNT command. If the server parameter file is not available,
RMAN attempts to start the instance with a dummy server parameter file. The ORA-
01078 and LRM-00109 errors are normal and can be ignored.
RMAN> STARTUP NOMOUNT
mkdir -p /u01/app/oracle/admin/db1/adump
10. If block change tracking was enabled on the original database, create the directory for
the block change tracking file. This will be a directory under db_create_file_dest.
Search the spfile for the name of the directory.
strings ${ORACLE_HOME}/dbs/spfile${ORACLE_SID}.ora | grep db_create_file_dest
*.db_create_file_dest='/u02/app/oracle/oradata/db1'
11. Restart the instance with the restored server parameter file.
STARTUP FORCE NOMOUNT;
12. Restore the controlfile from the RMAN autobackup and mount the database.
set controlfile autobackup format for device type sbt to '%F';
run {
allocate channel c1 device type sbt PARMS 'SBT_LIBRARY=/home/oracle/lib/libopc.so, SBT_PARMS=
(OPC_PFILE=/home/oracle/config)';
restore controlfile from autobackup;
alter database mount;
}
14. RMAN will recover using archived redo logs until it can't find any more. It is normal for
an error similar to the one below to occur when RMAN has applied the last archived redo
log in the backup and can't find any more logs.
unable to find archived log
archived log thread=1 sequence=29
RMAN-00571: ===========================================================
RMAN-00569: =============== ERROR MESSAGE STACK FOLLOWS ===============
RMAN-00571: ===========================================================
RMAN-03002: failure of recover command at 06/28/2016 00:57:35
RMAN-06054: media recovery requesting unknown archived log for thread 1 with sequence 29 and
starting SCN of 2349563
The recovery is complete. The database will have all of the committed transactions as of the
last backed up archived redo log.
Note
To initiate the recovery, you'll use the Oracle Database CLI Reference command and specify
the recovery type parameter (either --recoverytype or just -t). You can specify the
following types of recovery:
The dbcli create-recovery attempts to perform a full recovery of the database. For
information on performing a partial recovery (datafile, tablespace and PDB), see the Oracle
Database Backup Recovery Guide for version 18.1, 12.2, 12.1, or 11.2.
PREREQUISITES
l The backup must have been created with the dbcli create-backup command.
l If the database is configured with Transparent Data Encryption (TDE), make sure the
password-based and autologin TDE wallets are present in the following location:
/opt/oracle/dcs/commonstore/wallets/tde/<db_unique_name>
2. Log in as opc and then sudo to the root user. Use sudo su - with a hyphen to invoke the
root user's profile, which will set the PATH to the dbcli directory
(/opt/oracle/dcs/bin).
login as: opc
3. Find the ID of database you want to recover by using the dbcli list-databases command.
You'll need the ID for the following step.
[root@dbsys ~]# dbcli list-databases
ID DB Name DB Version CDB Class Shape
Storage Status
---------------------------------------- ---------- ---------- ---------- -------- -------- -----
----- ----------
5a3e980b-e0fe-4909-9628-fcefe43b3326 prod 12.1.0.2 true OLTP odb1 ACFS
Configured
4. Initiate the recovery by using the Oracle Database CLI Reference command and
specifying the database ID, recovery type parameter (-t), and any parameter required
for the recover type, like the time stamp or system change number.
The following example initiates a complete recovery.
[root@dbsys ~]# dbcli create-recovery --dbid 5a3e980b-e0fe-4909-9628-fcefe43b3326 --recoverytype
Latest
{
"jobId" : "c9f81228-2ce9-43b4-88f6-b260d398cf06",
"status" : "Created",
"message" : null,
"reports" : [ ],
"createTimestamp" : "August 08, 2016 18:20:47 PM UTC",
"description" : "Create recovery for database id :5a3e980b-e0fe-4909-9628-fcefe43b3326",
"updatedTime" : "August 08, 2016 18:20:47 PM UTC"
}
Job details
----------------------------------------------------------------
ID: c9f81228-2ce9-43b4-88f6-b260d398cf06
Description: Create recovery for database id :5a3e980b-e0fe-4909-9628-fcefe43b3326
Status: Success
Created: August 8, 2016 6:20:47 PM UTC
Message:
You can also check the database restore report logs on the DB System at:
/opt/oracle/dcs/log/<nodename>/rman/bkup/<db_unique_name>
Recovering a Database from the Oracle Cloud Infrastructure Classic Object Store
Note
This topic explains how to recover a database using a backup created by the Oracle Database
Backup Module and stored in Oracle Cloud Infrastructure Object Storage Classic.
PREREQUISITES
l The service name, identity name, container, user name, and password for Oracle Cloud
Infrastructure Object Storage Classic.
l The backup password if password-based encryption was used when backing up to Object
Storage Classic.
l The source database ID, database name, database unique name (required for setting up
storage).
l If the source database is configured with Transparent Data Encryption (TDE), you'll
need a backup of the wallet and the wallet password.
l Tnsnames to setup for any database links.
l The output of Opatch lsinventory for the source database Oracle_home, for
reference.
l A copy of the sqlpatch directory from the source database home. This is required for
rollback in case the target database does not include these patches.
2. Log in as opc and then sudo to the root user. Use sudo su - with a hyphen to invoke the
root user's profile, which will set the PATH to the dbcli directory
(/opt/oracle/dcs/bin).
login as: opc
3. Use the dbcli create-dbstorage command to set up directories for DATA, RECO, and
REDO storage. The following example creates 10GB of ACFS storage for the tdetest
database.
[root@dbsys ~]# dbcli create-dbstorage --dbname tdetest --dataSize 10 --dbstorage ACFS
Note
4. Use the dbcli list-dbstorages command to list the storage ID. You'll need the ID for the
next step.
[root@dbsys ~]# dbcli list-dbstorages
ID Type DBUnique Name Status
---------------------------------------- ------ -------------------- ----------
9dcdfb8e-e589-4d5f-861a-e5ba981616ed Acfs tdetest Configured
5. Use the dbcli describe-dbstorage command with the storage ID from the previous step
to list the DATA, RECO and REDO locations.
[root@dbsys ~]# dbcli describe-dbstorage --id 9dcdfb8e-e589-4d5f-861a-e5ba981616ed
DBStorage details
----------------------------------------------------------------
ID: 9dcdfb8e-e589-4d5f-861a-e5ba981616ed
DB Name: tdetest
DBUnique Name: tdetest
DB Resource ID:
Storage Type: Acfs
DATA Location: /u02/app/oracle/oradata/tdetest
RECO Location: /u03/app/oracle/fast_recovery_area/
REDO Location: /u03/app/oracle/redo/
State: ResourceState(status=Configured)
Created: August 24, 2016 5:25:38 PM UTC
UpdatedTime: August 24, 2016 5:25:53 PM UTC
6. Note the DATA, RECO and REDO locations. You'll need them later to set the db_create_
file_dest, db_create_online_log_dest, and db_recovery_file_dest parameters
for the database.
CHOOSING AN ORACLE_HOME
Decide which ORACLE_HOME to use for the database restore and then switch to that home
with the correct ORACLE_BASE, ORACLE_HOME, and PATH settings. The ORACLE_HOME must
not already be associated with a database.
To get a list of existing ORACLE_HOMEs and to ensure that the ORACLE_HOME is empty, use
the dbcli list-dbhomes and the dbcli list-databases commands, respectively. To create a new
ORACLE_HOME, use the dbcli create-dbhome command.
Skip this section if the source database is not configured with TDE.
3. Copy the ewallet.p12 file from the source database to the directory you created in the
previous step.
4. On the target host, make sure that $ORACLE_HOME/network/admin/sqlnet.ora
Add the line if it doesn't exist in the file. (The line might not be there if this is a new
home and no database has been created yet on this host.)
5. Create the autologin wallet from the password-based wallet to allow auto-open of the
wallet during restore and recovery operations.
For a version 12.1 or later database, use the ADMINISTER KEY MANAGEMENT command:
$cat create_autologin_12.sh
#!/bin/sh
if [ $# -lt 2 ]; then
echo "Usage: $0 <dbuniquename><remotewalletlocation>"
exit 1;
fi
mkdir /opt/oracle/dcs/commonstore/wallets/tde/$1
cp $2/ewallet.p12* /opt/oracle/dcs/commonstore/wallets/tde/$1
rm -f autokey.ora
echo "db_name=$1" > autokey.ora
autokeystoreLog="autologinKeystore_`date +%Y%m%d_%H%M%S_%N`.log"
echo "Enter Keystore Password:"
read -s keystorePassword
echo "Creating AutoLoginKeystore -> "
sqlplus "/as sysdba" <<EOF
spool $autokeystoreLog
set echo on
startup nomount pfile=autokey.ora
ADMINISTER KEY MANAGEMENT CREATE AUTO_LOGIN KEYSTORE
FROM KEYSTORE '/opt/oracle/dcs/commonstore/wallets/tde/$1' -- Keystore location
IDENTIFIED BY "$keystorePassword";
shutdown immediate;
EOF
total 20
The backup module JAR file is included on the DB system but you need to install it.
1. SSH to the DB system, log in as opc, and then become the oracle user.
ssh -i <path to SSH key used when launching the DB System> opc@<DB System IP address or hostname>
sudo su - oracle
2. Change to the directory that contains the backup module opc_install.jar file.
cd /opt/oracle/oak/pkgrepos/orapkgs/oss/<version>/
3. Use the command syntax described in Installing the Oracle Database Cloud Backup
Module to install the backup module.
Set the following environment variables for the RMAN and SQL*Plus sessions for the
database:
ORACLE_HOME=<path of Oracle Home where the database is to be restored>
ORACLE_SID=<database instance name>
ORACLE_UNQNAME=<db_unique_name in lower case>
NLS_DATE_FORMAT="mm/dd/yyyy hh24:mi:ss"
ALLOCATING AN RMAN SBT CHANNEL
For each restore operation, allocate an SBT channel and set the SBT_LIBRARY parameter to
the location of the libopc.so file and the OPC_FILE parameter to the location of the opc_
sbt.ora file, for example:
ALLOCATE CHANNEL c1 DEVICE TYPE sbt MAXPIECESIZE 2 G FORMAT '%d_%I_%U' PARMS 'SBT_
LIBRARY=/tmp/oss/libopc.so ENV=(OPC_PFILE=/<ORACLE_HOME>/dbs/opc_sbt.ora)';
(For more information about these files, see Files Created When the Backup Module is
Installed.)
Make sure that decryption is turned on for all the RMAN restore sessions.
set decryption wallet open identified by <keystore password>;
For more information, see Providing Password Required to Decrypt Encrypted Backups.
RESTORING S PFILE
The following sample shell script restores the spfile. Set the $dbID variable to the dbid of the
database being restored. By default, spfile is restored to $ORACLE_
HOME/dbs/spfile<sid>.ora.
rman target / <<EOF
3. Remove the control_files parameter. The Oracle Managed Files (OMF) parameters
will be used to create the control file.
alter system reset control_files scope=spfile;
4. Restart the database in nomount mode using the newly added parameters.
shutdown immediate
startup nomount
Modify the following sample shell script for your environment to restore the control file. Set
the $dbID variable to the dbid of the database being restored. Set SBT_LIBRARY to the
location specified in the -libDir parameter when you installed the Backup Module. Set OPC-
PFILE to the location specified in the -configFile parameter, which defaults to ORACLE_
HOME/dbs/opcSID.ora.
rman target / <<EOF
SET DBID=$dbID;
RESTORE CONTROLFILE FROM AUTOBACKUP;
alter database mount;
}
exit;
EOF
1. Preview and validate the backup. The database is now mounted and RMAN should be
able to locate the backup from the restored controlfile. This step helps ensure that the
list of archivelogs is present and that the backup components can be restored .
In the following examples, modify SBT_LIBRARY and OPC_PFILE as needed for your
environment.
rman target / <<EOF
Review the output and if there are error messages, investigate the cause of the
problem.
2. Redirect the restore using set newname to restore the data files in OMF format and use
switch datafile all to allow the control file to update with the new data file copies.
rman target / <<EOF
ALLOCATE CHANNEL c1 DEVICE TYPE sbt MAXPIECESIZE 2 G FORMAT '%d_%I_%U' PARMS 'SBT_
LIBRARY=/tmp/oss/libopc.so ENV=(OPC_PFILE=/tmp/oss/opc_sbt.ora)';
ALLOCATE CHANNEL c2 DEVICE TYPE sbt MAXPIECESIZE 2 G FORMAT '%d_%I_%U' PARMS 'SBT_
LIBRARY=/tmp/oss/libopc.so ENV=(OPC_PFILE=/tmp/oss/opc_sbt.ora)';
ALLOCATE CHANNEL c3 DEVICE TYPE sbt MAXPIECESIZE 2 G FORMAT '%d_%I_%U' PARMS 'SBT_
LIBRARY=/tmp/oss/libopc.so ENV=(OPC_PFILE=/tmp/oss/opc_sbt.ora)';
set newname for database to new;
restore database;
switch datafile all;
switch tempfile all;
recover database;
}
This recovery will attempt to use the last available archive log backup and then fail with
an error, for example:
RMAN-00571: ===========================================================
RMAN-00569: =============== ERROR MESSAGE STACK FOLLOWS ===============
RMAN-00571: ===========================================================
RMAN-03002: failure of recover command at 07/20/2016 12:09:02
RMAN-06054: media recovery requesting unknown archived log for thread 1 with sequence 22 and
starting SCN of 878327
3. To complete the incomplete recovery, run a recovery using the sequence number and
thread number shown in the RMAN-06054 message, for example:
Recover database until sequence 22 thread 1;
1. Make sure the database COMPATIBLE parameter value is acceptable. If the value is less
than the minimum, the database cannot be registered until you upgrade the database
compatibility.
The minimum compatibility values are as follows:
3. Make sure the password file was restored or created for the new database.
ls -ltr $ORACLE_HOME/dbs/orapw<oracle sid>
If the file does not exist, create it using the orapwd utility.
orapwd file=<$ORACLE_HOME/dbs/orapw<$ORACLE_SID>> password=<sys password>
The command output should indicate read write mode. The dbcli register-database
command will attempt to run datapatch, which requires read write mode. If there are
PDBs, they should also be in read write mode to ensure that datapatch runs on them.
5. From oracle home on the restored database, use the following command verify the
connection to SYS:
conn sys/<password>@//<hostname>:1521/<database service name>
This connection is required to register the database later. Fix any connection issues
before continuing.
6. Make sure the database is running on spfile by using the SQL*Plus command.
SHOW PARAMETERS SPFILE
7. (Optional) If you would like to manage the database backup with the dbcli command line
interface, you can associate a new or existing backup configuration with the migrated
database when you register it or after you register it. A backup configuration defines the
backup destination and recovery window for the database. Use the following commands
to create, list, and display backup configurations:
l dbcli update-backupconfig
l dbcli list-backupconfigs
l dbcli describe-backupconfig
8. Copy the folder $ORACLE_HOME/sqlpatch from source database to the target database.
This will enable the dbcli register-database command to roll back any conflicting
patches.
Note
The dbcli register-database command registers the restored database to the dcs-agent so it
can be managed by the dcs-agent stack.
Note
As the root user, use the dbcli register-database command to register the database on
the DB system, for example:
[root@dbsys ~]# dbcli register-database --dbclass OLTP --dbshape odb1 --servicename tdetest --
syspassword
Password for SYS:
{
"jobId" : "317b430f-ad5f-42ae-bb07-13f053d266e2",
"status" : "Created",
"message" : null,
"reports" : [ ],
"createTimestamp" : "August 08, 2016 05:55:49 AM EDT",
"description" : "Database service registration with db service name: tdetest",
"updatedTime" : "August 08, 2016 05:55:49 AM EDT"
}
UPDATING TNSNAMES.ORA
Check the tnsnames.ora in the backup location, check the database links used in the cloned
database, and then add any relevant connection strings to the cloned database file at
$ORACLE_HOME/network/admin/tnsnames.ora.
For version 11.2 databases, the sqlpatch application is not automated, so any interim patches
(previously known as a "one-off" patches) applied to the source database that are not part of
the installed PSU must be rolled back manually in the target database. After registering the
database, execute the catbundle.sql script and then the postinstall.sql script with the
corresponding PSU patch (or the overlay patch on top of the PSU patch), as described below.
Tip
1. On the DB System, use the dbcli list-dbhomes command to find the PSU patch
number for the version 11.2 database home. In the following sample command output,
the PSU patch number is the second number in the DB Version column:
(The first patch number, 23054319 in the example above, is for the OCW component in
the database home.)
2. Find the overlay patch, if any, by using the lsinventory command. In the following
example, patch number 24460960 is the overlay patch on top of the 23054359 PSU
patch.
$ $ORACLE_HOME/OPatch/opatch lsinventory
...
Installed Top-level Products (1):
4. Apply the sqlpatch, using the overlay patch number from the previous step, for
example:
SQL> connect / as sysdba
SQL> @$ORACLE_HOME/sqlpatch/24460960/postinstall.sql
exit
Note
After the database is restored and registered on the DB system, use the following checklist to
verify the results and perform any post-restore customizations.
l Database links: Make sure all the required TNS entries are updated in the
tnsnames.ora file in ORACLE_HOME.
l Email and URLs: Make sure any email addresses and URLs used in the database
are still accessible from the DB system.
l Scheduled jobs: Review the jobs scheduled in source database and schedule
similar jobs as needed in the restored database.
4. If you associated a backup configuration when you registered the database, run a test
back up using the dbcli create-backup command.
5. If the restored database contains a CDB and PDBs, verify that patches have been
applied to all PDBs.
Note
This topic explains how to use the Console to manage Oracle Data Guard associations in your
DB system. To configure an Oracle Data Guard system across regions or between on-
premises and Oracle Cloud Infrastructure DB systems, you must access the database host
directly and use the DGMGRL utility.
For complete information on Oracle Data Guard, see the Data Guard Concepts and
Administration documentation on the Oracle Document Portal.
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.
If you are new to policies, then see Getting Started with Policies and Common Policies.
Prerequisites
An Oracle Data Guard implementation requires two DB systems, one containing the primary
database and one containing the standby database. When you enable Oracle Data Guard for a
virtual machine DB system database, a new DB system with the standby database is created
and associated with the primary database. For a bare metal DB system, the DB system with
the database that you want to use as the standby must already exist before you enable Oracle
Data Guard.
Tip
l The database version determines whether Active Data Guard is enabled. If you are
using the BYOL licensing model and if your license does not include Active Data Guard,
then you must either use Oracle Database Enterprise Edition - High Performance or set
up Oracle Data Guard manually. See Using Oracle Data Guard with the Database CLI.
l If your primary and standby databases are in different regions, then you must peer the
virtual cloud networks (VCNs) for each database. See Remote VCN Peering (Across
Regions).
l Configure the security list ingress and egress rules for the subnets of both DB systems
in the Oracle Data Guard association to enable TCP traffic to move between the
applicable ports. Ensure that the rules you create are stateful (the default).
For example, if the subnet of the primary DB system uses the source CIDR 10.0.0.0/24
and the subnet of the standby DB system uses the source CIDR 10.0.1.0/24, then create
rules as shown in the subsequent example.
Note
Egress Rules:
Stateless: No
Destination: 10.0.1.0/24
IP Protocol: TCP
Source Port Range: All
Destination Port Range: 1521
Allows: TCP traffic for ports: 1521
Stateless: No
Source: 10.0.0.0/24
IP Protocol: TCP
Source Port Range: All
Destination Port Range: 1521
Allows: TCP traffic for ports: 1521
Egress Rules:
Stateless: No
Destination: 10.0.0.0/24
IP Protocol: TCP
Source Port Range: All
Destination Port Range: 1521
Allows: TCP traffic for ports: 1521
For information about creating and editing rules, see Security Lists.
Availability Domain and Fault Domain Considerations for Oracle Data Guard
Oracle recommends that the DB system that contains the standby database be in a different
availability domain from that of the DB system containing the primary database to improve
availability and disaster recovery. If you enable Oracle Data Guard for a database and your
standby database is in the same availability domain as the primary database (either by
choice, or because you are working in a single availability domain region), then Oracle
recommends that you place the standby database in a different fault domain from that of the
primary database.
Note
Oracle Data Guard ensures high availability, data protection, and disaster recovery for
enterprise data. The Oracle Cloud Infrastructure Database Data Guard implementation
requires two databases: one in a primary role and one in a standby role. The two databases
make an Oracle Data Guard association. Most of your applications access the primary
database, while the standby database is a transactionally consistent copy of the primary
database.
Oracle Data Guard maintains the standby database by transmitting and applying redo data
from the primary database. If the primary database becomes unavailable, then you can use
Oracle Data Guard to switch or fail over the standby database to the primary role.
Tip
S WITCHOVER
A switchover reverses the primary and standby database roles. Each database continues to
participate in the Oracle Data Guard association in its new role. A switchover ensures no data
loss. Performing planned maintenance on a DB system with an Oracle Data Guard association
is typically done by switching the primary database to the standby role, performing
maintenance on the standby database, and then switching it back to the primary role.
FAILOVER
A failover transitions the standby database into the primary role after the existing primary
database fails or becomes unreachable. A failover might result in some data loss when you
use Maximum Performance protection mode.
REINSTATE
Reinstates a database into the standby role in an Oracle Data Guard association. You can use
the reinstate command to return a failed database into service after correcting the cause of
failure.
Note
If you want to terminate a DB system that has Data Guard enabled, you must terminate the
standby DB system before terminating the primary DB system. If you try to terminate a
primary DB system that has a standby, the terminate operation will not complete. See To
terminate a DB system for instructions on terminating a DB system.
Use the Console to enable an Oracle Data Guard association between databases, change the
role of a database in an Oracle Data Guard association using either a switchover or a failover
operation, and reinstate a failed database.
When you enable Oracle Data Guard, a separate Oracle Data Guard association is created for
the primary and the standby databases.
Note
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose the Compartment that contains a DB system with a database for which you
want to enable Oracle Data Guard.
3. Click the name of a DB system that contains a database you want to assume the
primary role.
4. On the DB System Details page, in the Databases section, click the name of the
database you want to make primary.
5. On the Database Details page, in the Resources section, click Data Guard
Associations.
6. In the Data Guard Associations section, click Enable Data Guard.
7. On the Enable Data Guard page, configure the Oracle Data Guard association.
l The settings in the Data Guard association details section are read only and
cannot be changed.
o Protection mode: The protection mode used for this Oracle Data Guard
association is set to Maximum Performance.
o Transport type: The redo transport type used for this Oracle Data Guard
association is set to Async (asynchronous).
l In the Select peer DB system section, provide the following information for the
standby database to obtain a list of available DB systems in which to locate the
standby database:
o Region: Select a region where you want to locate the standby database.
The region where the primary database is located is selected, by default.
You can choose to locate the standby database in a different region. The hint
text associated with this field tells you in which region the primary database
is located.
o Availability domain: Select an availability domain for the standby
database. The hint text associated with this field tells you in which
availability domain the primary database is located.
Note
o Shape: Select the shape of the DB system in which to locate the standby
database. The shape can be another bare metal DB system shape.
o Peer DB system: Select a DB system in which to locate the standby
database.
l In the Configure standby database section, enter the database administrator
password of the primary database in the Database password field. Use this
same database administrator password for the standby database.
8. Click Enable Data Guard.
When you create the association, the details for a database and its peer display their
respective roles as Primary or Standby.
primary role, then create a database as described in Creating Bare Metal and Virtual Machine
DB Systems. A new DB system includes an initial database. When you enable Oracle Data
Guard on the primary database, a virtual machine DB system gets created for the standby
database.
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose the Compartment that contains a DB system with a database for which you
want to enable Oracle Data Guard.
3. Click the name of a DB system that contains a database you want to assume the
primary role.
4. On the DB System Details page, in the Databases section, click the name of the
database you want to make primary.
5. On the Database Details page, in the Resources section, click Data Guard
Associations.
6. In the Data Guard Associations section, click Enable Data Guard.
7. On the Enable Data Guard page, configure your Oracle Data Guard association.
l The settings in the Data Guard association details section are read only and
cannot be changed.
o Protection mode: The protection mode used for this Oracle Data Guard
association is set to Maximum Performance.
o Transport type: The redo transport type used for this Oracle Data Guard
association is set to Async (asynchronous).
l Specify the following values in the Create peer DB system section for the
standby database:
o Display name: Enter a non-unique display name for the DB system
containing the standby database. An Oracle Cloud Identifier (OCID) will
uniquely identify the DB system.
o Region: Select a region where you want to locate the standby database.
The region where the primary database is located is selected, by default.
You can choose to locate the standby database in a different region. The hint
text associated with this field tells you in which region the primary database
is located.
o Availability domain: Select an availability domain for the standby
database. The hint text associated with this field tells you in which
availability domain the primary database is located.
Note
Note
Note
n Hostname prefix: Enter a host name prefix for the DB system that
contains the standby database. The host name must begin with an
alphabetic character, and can contain only alphanumeric characters
and hyphens (-). The maximum number of characters allowed for
bare metal and virtual machine DB systems is 16.
Importa
nt
n Host domain name: The domain name for the DB system. If the
subnet you selected uses the Oracle-provided internet and virtual
cloud network resolver for DNS name resolution, then this field
displays the domain name for the subnet, which you cannot change.
Otherwise, you can enter a domain name. Hyphens (-) are not
permitted.
n Host and domain URL: Combines the host and domain names to
display the fully-qualified domain name for the database. The
maximum length is 64 characters.
o In the Configure standby database section, enter the database
administrator password of the primary database in the Database
password field. Use this same database administrator password for the
standby database.
l Database Admin Password: Enter the primary database admin password.
The same password is used for the standby database.
Confirm Database Admin Password: Re-enter the Database Admin Password
you specified.
8. Click Enable Data Guard.
When you create the association, the details for a database and its peer display their
respective roles as Primary or Standby.
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose the Compartment that contains the DB system with the primary database you
want to switch over.
3. Click the DB system name, and then click the name of the primary database.
4. Under Resources, click Data Guard Associations.
5. For the Data Guard association on which you want to perform a switchover, click the
Actions icon (three dots), and then click Switchover.
6. In the Switchover Database dialog box, enter the database admin password, and
then click OK.
This database should now assume the role of the standby, and the standby should
assume the role of the primary in the Data Guard association.
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose the Compartment that contains the DB system with the primary database's
peer standby you want to fail over to.
3. Click the DB system name, and then click the name of the standby database.
4. Under Resources, click Data Guard Associations.
5. For the Data Guard association on which you want to perform a failover, click Failover.
6. In the Failover Database dialog box, enter the database admin password, and then
click OK.
This database should now assume the role of the primary, and the old primary's role
should display as Disabled Standby.
To reinstate a database
After you fail over a primary database to its standby, the standby assumes the primary role
and the old primary is identified as a disabled standby. After you correct the cause of failure,
you can reinstate the failed database as a functioning standby for the current primary by using
its Data Guard association.
Note
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose the Compartment that contains the DB system with the failed database you
want to reinstate.
3. Click the DB system name, and then click the database name.
4. Under Resources, click Data Guard Associations.
5. For the Data Guard association on which you want to reinstate this database, click the
Actions icon (three dots), and then click Reinstate.
6. In the Reinstate Database dialog box, enter the database admin password, and then
click OK.
This database should now be reinstated as the standby in the Data Guard association.
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose the Compartment that contains the DB system that includes the standby
database you want to terminate.
3. Click the DB system name.
4. For the standby database you want to terminate, click the Actions icon (three dots), and
then click Terminate.
5. In the Terminate Database dialog box, enter the name of the database, and then click
OK.
1. Open the navigation menu. Under Database, click Bare Metal, VM, and Exadata.
2. Choose the Compartment that contains the standby DB system that you want to
terminate.
3. Click the DB system name, click the Actions icon (three dots), and then click
Terminate.
4. Confirm when prompted.
The DB system's icon indicates Terminating.
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.
l CreateDataGuardAssociation
l GetDataGuardAssociation
l ListDataGuardAssociations
l SwitchoverDataGuardAssociation
l FailoverDataGuardAssociation
l ReinstateDataGuardAssociation
l DeleteDbHome - To terminate a bare metal DB system Data Guard association, delete
the standby database.
l TerminateDbSystem - To terminate a virtual machine DB system Data Guard
association, terminate the standby DB system.
For the complete list of APIs for the Database service, see Database Service API.
Note
This topic explains how to use the database CLI to set up Data Guard with Fast-Start Failover
(FSFO) in Oracle Cloud Infrastructure. The following sections explain how to prepare the
primary and standby databases, and then configure Data Guard to transmit redo data from the
primary database and apply it to the standby database.
Note
Prerequisites
To perform the procedures in this topic, you'll need the following information for the primary
and standby databases.
2. Log in as opc and then sudo to the root user. Use sudo su - with a hyphen to invoke the
root user's profile, which will set the PATH to the dbcli directory
(/opt/oracle/dcs/bin).
login as: opc
3. To find the db_name (or oracle_sid) and db_uniqueName, run the dbcli list-
databases -j command.
[root@dbsys ~]# dbcli list-databases -j
[ {
"id" : "80ad855a-5145-4f8f-a08f-406c5e4684ff",
"name" : "dbtst",
"dbName" : "dbtst",
"databaseUniqueName" : "dbtst_phx1cs",
"dbVersion" : "12.1.0.2",
"dbHomeId" : "2efe7af7-0b70-4e9b-ba8b-71f11c6fe287",
"instanceOnly" : false,
.
.
.
4. To find the oracle home directory (or database home), run the dbcli list-dbhomes
command. If there are multiple database homes on the DB system, use the one that
matches the "dbHomeId" in the dbcli list-databases -j command output shown
above.
[root@dbtst ~]# dbcli list-dbhomes
ID Name DB Version
Home Location Status
---------------------------------------- -------------------- -----------------------------------
----- --------------------------------------------- ----------
2efe7af7-0b70-4e9b-ba8b-71f11c6fe287 OraDB12102_home1 12.1.0.2.160719 (23739960,
23144544) /u01/app/oracle/product/12.1.0.2/dbhome_1 Configured
33ae99fe-5413-4392-88da-997f3cd24c0f OraDB11204_home1 11.2.0.4.160719 (23054319,
23054359) /u01/app/oracle/product/11.2.0.4/dbhome_1 Configured
If you don't already have a primary DB system, create one as described in Creating Bare
Metal and Virtual Machine DB Systems. The DB system will include an initial database. You
can create additional databases by using the dbcli create-database command available on the
DB system.
Note
1. Create a standby DB system as described in Creating Bare Metal and Virtual Machine DB
Systems and wait for the DB system to finish provisioning and become available.
You can create the standby DB system in a different availability domain from the
primary DB system for availability and disaster recovery purposes (this is strongly
recommended). You can create the standby DB system in the primary DB system's
cloud network so that both systems are in a single, routable network.
2. SSH to the DB System.
ssh -i <private_key_path> opc@<db_system_ip_address>
3. Log in as opc and then sudo to the root user. Use sudo su - with a hyphen to invoke the
root user's profile, which will set the PATH to the dbcli directory
(/opt/oracle/dcs/bin).
login as: opc
4. The DB system will include an initial database, but you'll need to create a standby
database by using the dbcli create-database command with the --instanceonly
parameter. This parameter creates only the database storage structure and starts the
database in nomount mode (no other database files are created).
When using --instanceonly, both the --dbname and --adminpassword parameters are
required and they should match the dbname and admin password of the primary
database to avoid confusion.
The following sample command prompts for the admin password and then creates a
storage structure for a database named dbname.
[root@dbsys ~]# dbcli create-database --dbname <same as primary dbname> --databaseUniqueName
<different from primary uniquename> --instanceonly --adminpassword
If you are using pluggable databases, also specify the --cdb parameter.
For complete command syntax, see dbcli create-database.
5. Wait a few minutes for the dbcli create-database command to create the standby
database.
You can use the dbcli list-jobs command to verify that the creation job ran
successfully, and then the dbcli list-databases command verify that the database is
configured.
To prepare the primary DB system, you'll need to configure static listeners, update
tnsnames.ora, and configure some database settings and parameters.
1. SSH to the primary DB system, log in as the opc or root user, and sudo to the grid
OS user.
sudo su - grid
SID_LIST_LISTENER=
(SID_LIST=
(SID_DESC=
(SDU=65535)
(GLOBAL_DBNAME = <primary_db_unique_name>.<primary_db_domain>)
(SID_NAME = <primary_oracle_sid>)
(ORACLE_HOME=<oracle_home_directory>)
(ENVS="TNS_ADMIN=<oracle_home_directory>/network/admin")
)
(SID_DESC=
(SDU=65535)
(GLOBAL_DBNAME = <primary_db_unique_name>_DGMGRL.<primary_db_domain>)
(SID_NAME = <primary_oracle_sid>)
(ORACLE_HOME=<oracle_home_directory>)
(ENVS="TNS_ADMIN=<oracle_home_directory>/network/admin")
)
)
The sample above assumes that name resolution is working and that the <standby_
server>.<domain> is resolvable at the primary database. You can also use the private IP
address of the standby server if the IP addresses are routable within a single cloud network
(VCN).
Tip
2. Identify the Broker configuration file names and locations. The commands used for this
depend on the type of database storage. If you're not sure of the database storage type,
use the dbcli list-databases command on the DB system.
For ACFS database storage, use the following commands to set the Broker configuration
files.
SQL> alter system set dg_broker_config_file1='/u02/app/oracle/oradata/<Primary db_unique_
name>/dbs/dr1<Primary db_unique_name>.dat';
SQL> alter system set dg_broker_config_file2='/u02/app/oracle/oradata/<Primary db_unique_
name>/dbs/dr2<Primary db_unique_name>.dat';
For ASM database storage, use the following commands to set the Broker configuration
files.
SQL> alter system set dg_broker_config_file1='+DATA/<Primary db_unique_name>/dr1<db_unique_
name>.dat';
SQL> alter system set dg_broker_config_file2='+DATA/<Primary db_unique_name>/dr2<db_unique_
name>.dat';
5. Add Standby Redo Logs (SRLs), based on the Online Redo Logs (ORLs). On a newly
launched DB system, there will be three ORLs of size 1073741824, so create four SRLs
of the same size.
You can use the query below to determine the number and size (in bytes) of the ORLs.
SQL> select group#, bytes from v$log;
GROUP# BYTES
---------- ----------
1 1073741824
2 1073741824
3 1073741824
There should be only one member in the SRL group (by default, a DB system is created
with only one member per SRL group). To ensure this, you can name the file with the
following syntax.
alter database add standby logfile thread 1 group 4 (<logfile name with full path>) size
1073741824, group 5(<logfile name with full path>) size 1073741824 ...
For ASM/OMF configurations, the above command uses the diskgroup instead of <logfile
name with full path>.
alter database add standby logfile thread 1 group 4 (+RECO) size 1073741824, group 5(+RECO) size
1073741824 ...
Tip
9. Perform a single switch redo log to activate archiving if database is newly created. (At
least one log must be archived prior to running the RMAN duplicate.)
SQL> alter system switch logfile;
Before you prepare the standby database, make sure the database home on the standby is the
same version as on the primary. (If the primary and standby databases are both newly
created with the same database version, the database homes will be the same.) If it is not,
create a database home that is the same version. You can use the dbcli list-dbhomes
command to verify the versions and the dbcli create-dbhome command to create a new
database home as needed.
To prepare the standby DB system, you'll need to configure static listeners, update
tnsnames.ora, configure TDE Wallet, create a temporary password file, verify connectivity,
run RMAN DUPLICATE, enable FLASHBACK, and then create the database service.
1. SSH to the standby DB system, log in as the opc or root user, and sudo to the grid
OS user.
sudo su - grid
4. Verify that the static listeners are available. The sample output below is for database
version 12.1.0.2. Note that the ...status UNKNOWN messages are expected at this
point.
$ lsnrctl status
Connecting to (DESCRIPTION=(ADDRESS=(PROTOCOL=IPC)(KEY=LISTENER)))
STATUS of the LISTENER
------------------------
Alias LISTENER
Version TNSLSNR for Linux: Version 12.1.0.2.0 - Production
Start Date 29-SEP-2016 21:09:19
Uptime 0 days 0 hr. 0 min. 5 sec
Trace Level off
Security ON: Local OS Authentication
SNMP OFF
Listener Parameter File /u01/app/12.1.0.2/grid/network/admin/listener.ora
Listener Log File /u01/app/grid/diag/tnslsnr/dg2/listener/alert/log.xml
Listening Endpoints Summary...
(DESCRIPTION=(ADDRESS=(PROTOCOL=ipc)(KEY=LISTENER)))
(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=10.0.1.24)(PORT=1521)))
Services Summary...
Service "dg2_phx2hx.oratst.org" has 1 instance(s).
Instance "dg2", status UNKNOWN, has 1 handler(s) for this service...
Service "dg2_phx2hx_DGMGRL.oratst.org" has 1 instance(s).
Instance "dg2", status UNKNOWN, has 1 handler(s) for this service...
The command completed successfully
As the oracle user, add the standby database net service name to $ORACLE_
HOME/network/admin/tnsnames.ora. $ORACLE_HOME is the database home where the
standby database is running.
<Primary db_unique_name> =
(DESCRIPTION =
(SDU=65535)
(ADDRESS = (PROTOCOL = TCP)(HOST = <primary_server>.<domain>) (PORT = 1521))
(CONNECT_DATA =
(SERVER = DEDICATED)
(SERVICE_NAME = <primary db_unique_name).<primary db_domain>)
)
)
<Standby db_unique_name> =
(DESCRIPTION =
(SDU=65535)
(ADDRESS = (PROTOCOL = TCP)(HOST = <standby_server>.<domain>) (PORT = 1521))
(CONNECT_DATA =
(SERVER = DEDICATED)
(SERVICE_NAME = <standby db_unique_name>.<db_domain>)
)
)
Copy the TDE wallet files from the primary DB system to standby DB system using SCP. The
following sample command assumes the SCP command is being run by the oracle OS user and
that the private key for oracle has been created and exists on the host where SCP is being run.
$ scp -i <private key> primary_server:/opt/oracle/dcs/commonstore/wallets/tde/<primary db_unique_name>/*
standby_server:/opt/oracle/dcs/commonstore/wallets/tde/<standby db_unique_name>
As the oracle user, create the following directory for database version 11.2.0.4. This step is
optional for version 12.2.0.1 and version 12.1.0.2.
[oracle@dbsys ~]$ mkdir -pv /u03/app/oracle/redo/<standby db_unique_name uppercase>/controlfile
As the oracle user, create the following directory to use as the audit file destination.
[oracle@dbsys ~]$ mkdir -p /u01/app/oracle/admin/<db_name>/adump
The password must be the same as the admin password of the primary database. Otherwise,
the RMAN duplicate step below will fail with: RMAN-05614: Passwords for target and
auxiliary connections must be the same when using active duplicate.
The database needs to be started in nomount mode with no spfile specified, but the
original init file contains an spfile parameter which will prevent the RMAN duplicate step
from working.
4. Set the ORACLE_UNQNAME environment variable to point to your DB_UNIQUE_NAME.
$ export ORACLE_UNQNAME =db_unique_name
Important
1. Make sure that the listener port 1521 is open in the security list(s) used for the primary
and standby DB systems. For more information, see Updating the Security List for the
DB System.
2. From the primary database, connect to standby database.
$ sqlplus sys/<password>@<standby net service name> as sysdba
If the primary database is large, you can allocate additional channels to improve
performance. For a newly installed database, one channel typically runs the database
duplication in a couple of minutes.
Make sure that there are no errors generated by the RMAN DUPLICATE command. If errors
occur, restart the database using the init.ora file (not spfile) in case it is generated under
$ORACLE_HOME/dbs as part of RMAN DUPLICATE.
In the following examples, use lowercase for the <Standby db_unique_name> unless
otherwise specified.
Oracle recommends creating a database service for the standby database by using srvctl.
$ rm $ORACLE_HOME/dbs/spfile<standby oracle_sid>.ora
$ rm $ORACLE_HOME/dbs/init<standby oracle_sid>.ora
7. Stop the database and start the standby database by using srvctl.
$ srvctl start database -d <standby db_unique_name>
Perform the following steps to complete the configuration of Data Guard and enable redo
transport from the primary database and redo apply in the standby database.
1. Run the dgmgrl command line utility from either the primary or standby DB system and
connect to the primary database using sys credentials.
DGMGRL> connect sys/<sys password>@<primary tns alias>
2. Create the Data Guard configuration and identify for the primary and standby
databases.
DGMGRL> create configuration mystby as primary database is <primary db_unique_name> connect
identifier is <primary tns alias>;
add database <standby db_unique_name> as connect identifier is <standby tns alias> maintained
as physical;
4. Verify that Data Guard setup was done properly. Run the following SQL in both the
primary and standby databases.
SQL> select FORCE_LOGGING, FLASHBACK_ON, OPEN_MODE, DATABASE_ROLE, SWITCHOVER_STATUS, DATAGUARD_
BROKER, PROTECTION_MODE from v$database;
5. Verify that Data Guard processes are initiated in the standby database.
SQL> select PROCESS,PID,DELAY_MINS from V$MANAGED_STANDBY;
7. Verify that the Data Guard configuration is working. Specifically, make sure redo
shipping and redo apply are working and that the standby is not unreasonably lagging
behind the primary.
DGMGRL> show configuration verbose
DGMGRL> show database verbose <standby db_unique_name>
DGMGRL> show database verbose <primary db_unique_name>
Any discrepancies, errors, or warnings should be resolved. You can also run a
transaction on the primary and verify that it's visible in the standby.
8. Verify that the Data Guard configuration is functioning as expected by performing
switchover and failover in both directions. Run show configuration after each
operation and make sure there are no errors or warnings.
Warning
The best practice for high availability and durability is to run the primary, standby, and
observer in separate availability domains. The observer determines whether or not to failover
to a specific target standby database. The server used for observer requires the Oracle Client
Administrator software, which includes the Oracle SQL NET and Broker.
1. Configure TNS alias names for both the primary and standby databases as described
previously, and verify the connection to both databases.
2. Change protection mode to either maxavailability or maxperformance (maxprotection is
not supported for FSFO).
To enable maxavailability:
DGMGRL> edit database <standby db_unique_name> set property 'logXptMode'='SYNC';
DGMGRL> edit database <primary db_unique_name> set property 'logXptMode'='SYNC';
DGMGRL> edit configuration set protection mode as maxavailability;
To enable maxperformance:
DGMGRL> edit configuration set protection mode as maxperformance;
DGMGRL> edit database <standby db_unique_name> set property 'logXptMode'='ASYNC';
DGMGRL> edit database <primary db_unique_name> set property 'logXptMode'='ASYNC';
6. Start the observer from Broker (it will run in the foreground, but can also be run in the
background).
DGMGRL> start observer
8. Always test failover in both directions to ensure that everything is working as expected.
Verify that FSFO is running properly by performing a shutdown abort of the primary
database.
The observer should start the failover to the standby database. If protection mode is set
to maxprotection, some loss of data can occur, based on the FastStartFailoverLaglimit
value.
Note
Operational Notes
l Oracle Database maintains logs of the dbcli command output in the dcscli.log and
dcs-agent.log files in the /opt/oracle/dcs/log/ directory.
l The database CLI commands and most parameters are case sensitive and should be
typed as shown. A few parameters are not case sensitive, as indicated in the parameter
descriptions, and can be typed in uppercase or lowercase.
Warning
Syntax
where:
The remainder of this topic contains syntax and other details about the commands.
Occasionally, new commands are added to the database CLI and other commands are updated
to support new features. You can use the following command to update the database CLI:
Use the cliadm update-dbcli command to update the database CLI with the latest new and
updated commands.
Note
SYNTAX
PARAMETERS
E XAMPLE
Agent Commands
l dbcli ping-agent
l dbcli list-agentConfigParameters
l dbcli update-agentConfigParameters
DBCLI PING-AGENT
SYNTAX
PARAMETERS
SYNTAX
PARAMETERS
SYNTAX
dbcli update-agentConfigParameters -n <parameter> [-v <value>] [-a] [-c] [-d] [-u] [-r] [-h] [-j]
PARAMETERS
Autologcleanpolicy Commands
The following commands are available to manage policies for automatic cleaning (purging) of
logs.
l dbcli create-autoLogCleanPolicy
l dbcli list-autoLogCleanPolicy
SYNTAX
PARAMETERS
Use the dbcli list-autoLogCleanPolicy command to list policies for automatic cleaning of
logs.
SYNTAX
PARAMETERS
Backup Commands
l dbcli create-backup
l dbcli getstatus-backup
l dbcli schedule-backup
Note
Before you can back up a database by using the dbcli create-backup command, you'll need to:
After a database is associated with a backup configuration, you can use the dbcli create-
backup command in a cron job to run backups automatically. You can use a cron utility such
as CronMaker to help build expressions. For more information, see
http://www.cronmaker.com.
SYNTAX
PARAMETERS
Note
-i --dbid The ID of the database to back up. Use the dbcli list-
databases command to get the database's ID.
-in --dbName The name of the database to back up. Use the dbcli list-
databases command to get the database's name.
E XAMPLES
The following command creates a backup of the specified database using the database ID.
[root@dbsys ~]# dbcli create-backup -i 573cadb2-0cc2-4c1c-9c31-595ab8963d5b
The following command creates a backup of the specified database using the database name
("mydb").
[root@dbsys ~]# dbcli create-backup -in mydb
DBCLI GETSTATUS-BACKUP
SYNTAX
PARAMETERS
SYNTAX
PARAMETERS
Backupconfig Commands
A backup configuration determines the backup destination and recovery window for database
backups. You create the backup configuration and then associate it with a database by using
the dbcli update-database command.
Warning
Note
After a database is associated with a backup configuration, you can use the dbcli create-
backup command in a cron job to run backups automatically. You can use a cron utility such
l dbcli create-backupconfig
l dbcli list-backupconfigs
l dbcli describe-backupconfig
l dbcli update-backupconfig
l dbcli delete-backupconfig
Use the dbcli create-backupconfig command to create a backup configuration that defines
the backup destination and recovery windows.
SYNTAX
PARAMETERS
-o --objectstoreswiftId The ID of the object store that contains the endpoint
and credentials for the Oracle Cloud Infrastructure
Object Storage service. Use the dbcli list-
objectstoreswifts command to get the object store
ID. Use the dbcli create-objectstoreswift command
to create an object store.
E XAMPLE
"jobId" : "4e0e6011-db53-4142-82ef-eb561658a0a9",
"status" : "Success",
"message" : null,
"reports" : [ {
"taskId" : "TaskParallel_919",
"taskName" : "persisting backup config metadata",
"taskResult" : "Success",
"startTime" : "November 18, 2016 20:21:25 PM UTC",
"endTime" : "November 18, 2016 20:21:25 PM UTC",
"status" : "Success",
"taskDescription" : null,
"parentTaskId" : "TaskSequential_915",
"jobId" : "4e0e6011-db53-4142-82ef-eb561658a0a9",
"tags" : [ ],
"reportLevel" : "Info",
"updatedTime" : "November 18, 2016 20:21:25 PM UTC"
} ],
"createTimestamp" : "November 18, 2016 20:21:25 PM UTC",
"description" : "create backup config:dbbkcfg1",
"updatedTime" : "November 18, 2016 20:21:25 PM UTC"
}
Use the dbcli list-backupconfigs command to list all the backup configurations in the DB
system.
SYNTAX
PARAMETERS
E XAMPLE
Use the dbcli describe-backupconfig command to show details about a specific backup
configuration.
SYNTAX
PARAMETERS
E XAMPLE
ID: ccdd56fe-a40b-4e82-b38d-5f76c265282d
Name: dbbkcfg1
RecoveryWindow: 7
BackupDestination: Disk
CreatedTime: July 10, 2016 12:24:08 PM UTC
UpdatedTime: July 10, 2016 12:24:08 PM UTC
SYNTAX
dbcli update-backupconfig -i <id> -in <name> -w <n> -c <bucket> -o <object_store_swift_id> -on <object_
store_swift_name> [-cr|-no-cr] [-h] [-j]
PARAMETERS
-o --objectstoreswiftId The ID of the object store that contains the endpoint
and credentials for the Oracle Cloud Infrastructure
Object Storage service. Use the dbcli list-
objectstoreswifts command to get the object store
ID. Use the dbcli create-objectstoreswift command to
create an object store.
E XAMPLE
The following command updates the recovery window for a backup configuration:
[root@dbsys ~]# dbcli update-backupconfig -i ccdd56fe-a40b-4e82-b38d-5f76c265282d -w 5
{
"jobId" : "0e849291-e1e1-4c7a-8dd2-62b522b9b807",
"status" : "Created",
"message" : null,
"reports" : [ ],
"createTimestamp" : 1468153731699,
"description" : "update backup config: dbbkcfg1",
"updatedTime" : 1468153731700
}
SYNTAX
PARAMETERS
E XAMPLE
Bmccredential Commands
The following commands are available to manage credentials configurations, which are
required for downloading DB system patches from the Oracle Cloud Infrastructure Object
Storage service. For more information, see Patching a DB System.
l dbcli create-bmccredential
l dbcli list-bmccredentials
l dbcli describe-bmccredential
l dbcli delete-bmccredential
l dbcli update-bmccredential
Note
PREREQUISITES
Before you can create a credentials configuration, you'll need these items:
l An RSA key pair in PEM format (minimum 2048 bits). See How to Generate an API
Signing Key.
l The fingerprint of the public key. See How to Get the Key's Fingerprint.
l Your tenancy's OCID and user name's OCID. See Where to Get the Tenancy's OCID and
User's OCID.
Then you'll need to upload the public key in the Console. See How to Upload the Public Key.
SYNTAX
PARAMETERS
https://objectstorage.<region_name>.oraclecloud.com
-f --fingerPrint The public key fingerprint. You can find the fingerprint in
the Console by clicking your user name in the upper right
corner and then clicking User Settings. The fingerprint
looks something like this:
-f 61:9e:52:26:4b:dd:46:dc:8c:a8:05:6b:9f:0a:30:d2
-k --privateKey The path to the private key file in PEM format, for example:
-k /root/.ssh/privkey
E XAMPLE
{
"jobId" : "f8c80510-b717-4ee2-a47e-cd380480b28b",
"status" : "Created",
"message" : null,
"reports" : [ ],
Use the dbcli list-bmccredentials command to list the credentials configurations on the
DB system.
SYNTAX
PARAMETERS
E XAMPLE
SYNTAX
PARAMETERS
-i --id The ID for the credentials configuration. Use the dbcli list-
bmccredentials command to get the ID.
E XAMPLE
The following command displays details about the specified credentials configuration:
[root@dbsys ~]# dbcli describe-bmccredential -i 09f9988e-eed5-4dde-8814-890828d1c763
SYNTAX
PARAMETERS
-i --id The ID for the credentials configuration. Use the dbcli list-
bmccredentials command to get the ID.
E XAMPLE
SYNTAX
PARAMETERS
-i --id The ID for the credentials configuration. Use the dbcli list-
bmccredentials command to get the ID.
-k --privateKey The path to the private key file in PEM format, for example:
-k /root/.ssh/privkey
E XAMPLE
Component Command
Tip
Note
Use the dbcli describe-component command to show the installed and available patch
versions for the server, storage, and/or database home components in the DB system.
This command requires a valid Object Storage credentials configuration. Use the dbcli create-
bmccredential command to create the configuration if you haven't already done so. If the
configuration is missing or invalid, the command fails with the error: Failed to connect to
the object store. Please provide valid details.
For more information about updating the CLI, creating the credentials configuration, and
applying patches, see Patching a DB System.
SYNTAX
PARAMETERS
-d --dbhomes (Optional) Lists the installed and available patch versions for
only the database home components.
-s --server (Optional) Lists the installed and available patch versions for
only the server components.
E XAMPLE
The following command to show the current component versions and the available patch
versions in the object store:
[root@dbsys ~]# dbcli describe-component
System Version
---------------
12.1.2.10.0
Database Commands
l dbcli clone-database
l dbcli create-database
l dbcli delete-database
l dbcli describe-database
l dbcli list-databases
l dbcli modify-database
l dbcli recover-database
l dbcli register-database
l dbcli update-database
SYNTAX
dbcli clone-database -f <name> -u <name> -n <name> [-s <shape>] [-t <type>] [m <sys_password>] [-p <tde_
password>] [-h] [-j]
PARAMETERS
Use the dbcli create-database command to create a new database. You can create a
database with a new or existing Oracle Database home, however each database home can
have only one database.
It takes a few minutes to create the database. After you run the dbcli create-database
command, you can use the dbcli list-jobs command to check the status of the database
creation job.
Tip
Once the database is created, you can use the dbcli list-databases -j command to see
additional information about the database.
Note
SYNTAX
dbcli create-database -dh <db_home_id> -cl {OLTP|DSS|IMDB} -n <db_name> -u <unique_name> -bi <bkup_
config_id> -bn <bkup_config_name> -m -s <db_shape> -r {ACFS|ASM} -y {SI|RAC|RACOne} [-dn <name>] -io -d
<pdb_admin_user> [-p <pdb>] [-ns <nlcharset>] [-cs <charset>] [-l <language>] [-dt <territory>] -v
<version> [-c|-no-c] [-co|-no-co] [-h] [-j]
PARAMETERS
-cs --characterset (Optional) Defines the character set for the database.
The default is AL32UTF8.
-cl --dbclass Defines the database class. The options are OLTP,
DSS, or IMDB. The default is OLTP. For Enterprise
Editions, all three classes are supported. For
Standard Edition, only OLTP is supported.
-dt --dbterritory (Optional) Defines the territory for the database. The
default is AMERICA.
l 18.1.0.0
l 12.2.0.1
l 12.1.0.2 (the default)
l 11.2.0.4
USAGE NOTES
l You cannot mix Oracle Database Standard Edition and Enterprise Edition databases on
the same DB system. (You can mix supported database versions on the DB system, but
not editions.)
l When --dbhomeid is not provided, the dbcli create-database command will create a
new Oracle Database home.
Note
E XAMPLES
Note
SYNTAX
PARAMETERS
-in --dbName The name of the database to delete. Use the dbcli list-
databases command to get the database name.
E XAMPLE
SYNTAX
PARAMETERS
-i --dbid The ID of the database to display. Use the dbcli list-
databases command to get the database ID.
-in --dbName The name of the database to display. Use the dbcli list-
databases command to get the database name.
E XAMPLE
DB Home details
----------------------------------------------------------------
ID: b727bf80-c99e-4846-ac1f-28a81a725df6
Name: OraDB12102_home1
Version: 12.1.0.2
Home Location: /u01/app/orauser/product/12.1.0.2/dbhome_1
Created: Jun 2, 2016 10:19:23 AM
Use the dbcli list-databases command to list all databases on the DB system.
SYNTAX
PARAMETERS
E XAMPLE
DBCLI MODIFY-DATABASE
SYNTAX
PARAMETERS
SYNTAX
dbcli recover-database [-br <json>] [-in <db_name>] [-i <db_id>] [-r <time>] [-t {Latest|PITR|SCN}] [-s]
[-l <location>] [-tp <tde_password>] [-h] [-j]
PARAMETERS
Use the dbcli register-database command to register a database that has been migrated
to Oracle Cloud Infrastructure. The command registers the database to the dcs-agent so it can
be managed by the dcs-agent stack.
Note
SYNTAX
PARAMETERS
-bi --backupconfigid Defines the backup configuration ID. Use the dbcli
list-backupconfigs command to get the ID.
-c --dbclass Defines the database class. The options are OLTP, DSS,
or IMDB. The default is OLTP. For Enterprise Editions, all
three classes are supported. For Standard Edition, only
OLTP is supported.
-sn --servicename Defines the database service name used to build the
EZCONNECT string for connecting to the database. The
connect string format is hostname:port/servicename.
E XAMPLE
The following command registers the database with the specified database class, service
name, and database sizing template.
[root@dbsys ~]# dbcli register-database -c OLTP -s odb1 -sn crmdb.example.com -p
Password for SYS:
{
"jobId" : "317b430f-ad5f-42ae-bb07-13f053d266e2",
"status" : "Created",
"message" : null,
"reports" : [ ],
"createTimestamp" : "August 08, 2016 05:55:49 AM EDT",
"description" : "Database service registration with db service name: crmdb.example.com",
"updatedTime" : "August 08, 2016 05:55:49 AM EDT"
}
SYNTAX
dbcli update-database -i <db_id> -bi <bkup_config_id> -bin <bkup_config_name> [-id <id>] -in <name> [-
no-ab] [-h] [-j]
PARAMETERS
-bi --backupconfigid Defines the backup configuration ID. Use the dbcli
list-backupconfigs command to get the ID.
Note
E XAMPLE
Dbhome Commands
l dbcli create-dbhome
l dbcli describe-dbhome
l dbcli delete-dbhome
l dbcli list-dbhomes
l dbcli update-dbhome
SYNTAX
PARAMETERS
l 18.1.0.0
l 12.2.0.1
l 12.1.0.2
l 11.2.0.4
E XAMPLE
Use the dbcli describe-dbhome command to display Oracle Database Home details.
SYNTAX
PARAMETERS
E XAMPLE
The following output is an example of using the display Oracle Database Home details
command.
[root@dbsys ~]# dbcli describe-dbhome -i 52850389-228d-4397-bbe6-102fda65922b
DB Home details
----------------------------------------------------------------
ID: 52850389-228d-4397-bbe6-102fda65922b
Name: OraDB12102_home1
Version: 12.1.0.2
Home Location: /u01/app/oracle/product/12.1.0.2/dbhome_1
Created: June 29, 2016 4:36:31 AM UTC
Use the dbcli delete-dbhome command to delete a database home from the DB system.
SYNTAX
PARAMETERS
Use the dbcli list-dbhomes command to display a list of Oracle Home directories.
SYNTAX
PARAMETER
E XAMPLE
Tip
Use the dbcli update-dbhome command to apply the DBBP bundle patch to a database home.
For more information about applying patches, see Patching a DB System.
SYNTAX
PARAMETERS
E XAMPLE
The following commands update the database home and show the output from the update job:
[root@dbsys ~]# dbcli update-dbhome -i e1877dac-a69a-40a1-b65a-d5e190e671e6
{
"jobId" : "493e703b-46ef-4a3f-909d-bbd123469bea",
"status" : "Created",
"message" : null,
"reports" : [ ],
"createTimestamp" : "January 19, 2017 10:03:21 AM PST",
"resourceList" : [ ],
"description" : "DB Home Patching: Home Id is e1877dac-a69a-40a1-b65a-d5e190e671e6",
"updatedTime" : "January 19, 2017 10:03:21 AM PST"
}
Job details
----------------------------------------------------------------
ID: 493e703b-46ef-4a3f-909d-bbd123469bea
Description: DB Home Patching: Home Id is e1877dac-a69a-40a1-b65a-d5e190e671e6
Status: Running
Created: January 19, 2017 10:03:21 AM PST
Message:
Dbstorage Commands
l dbcli list-dbstorages
l dbcli describe-dbstorage
l dbcli create-dbstorage
l dbcli delete-dbstorage
Use the dbcli list-dbstorages command to list the database storage in the DB system.
SYNTAX
PARAMETERS
E XAMPLE
Use the dbcli describe-dbstorage command to show detailed information about a specific
database storage resource.
SYNTAX
PARAMETERS
-i --id Defines the database storage ID. Use the dbcli list-
dbstorages command to get the database storage ID.
E XAMPLE
The following command displays the database storage details for 105a2db2-625a-45ba-8bdd-
ee46da0fd83a:
[root@dbsys ~]# dbcli describe-dbstorage -i 105a2db2-625a-45ba-8bdd-ee46da0fd83a
DBStorage details
----------------------------------------------------------------
ID: 105a2db2-625a-45ba-8bdd-ee46da0fd83a
DB Name: db1
DBUnique Name: db1
DB Resource ID: 439e7bd7-f717-447a-8046-08b5f6493df0
Storage Type:
DATA Location: /u02/app/oracle/oradata/db1
RECO Location: /u03/app/oracle/fast_recovery_area/
REDO Location: /u03/app/oracle/redo/
State: ResourceState(status=Configured)
Created: July 3, 2016 4:19:21 AM UTC
UpdatedTime: July 3, 2016 4:41:29 AM UTC
Use the dbcli create-dbstorage command to create the database storage layout without
creating the complete database. This is useful for database migration and standby database
creation.
SYNTAX
dbcli create-dbstorage -n <db_name> [-u <db_unique_name>] [-r {ACFS|ASM}] [-s <datasize>] [-h] [-j]
PARAMETERS
E XAMPLE
The following command creates database storage with a storage type of ACFS:
[root@dbsys ~]# dbcli create-dbstorage -r ACFS -n testdb -u testdbname
{
"jobId" : "5884a77a-0577-414f-8c36-1e9d8a1e9cee",
"status" : "Created",
"message" : null,
"reports" : [ ],
"createTimestamp" : 1467952215102,
"description" : "Database storage service creation with db name: testdb",
"updatedTime" : 1467952215103
}
Use the dbcli delete-dbstorage command to delete database storage that is not being used
by the database. A error occurs if the resource is in use.
SYNTAX
PARAMETERS
-i --id The database storage ID to delete. Use the dbcli list-
dbstorages command to get the database storage ID.
E XAMPLE
{
"jobId" : "467c9388-18c6-4e1a-8655-2fd3603856ef",
"status" : "Running",
"message" : null,
"reports" : [ ],
"createTimestamp" : 1467952336843,
"description" : "Database storage service deletion with id: f444dd87-86c9-4969-a72c-fb2026e7384b",
"updatedTime" : 1467952336856
}
Dgconfig Commands
SYNTAX
PARAMETERS
Featuretracking Commands
SYNTAX
PARAMETERS
Job Commands
l dbcli describe-job
l dbcli list-jobs
Use the dbcli describe-job command to display details about a specific job.
SYNTAX
PARAMETERS
-i --jobid Identifies the job. Use the dbcli list-jobs command to get
the jobid.
E XAMPLE
The following command displays details about the specified job ID:
[root@dbsys ~]# dbcli describe-job -i 74731897-fb6b-4379-9a37-246912025c17
Job details
----------------------------------------------------------------
ID: 74731897-fb6b-4379-9a37-246912025c17
Description: Backup service creation with db name: dbtst
Status: Success
Created: November 18, 2016 8:33:04 PM UTC
Message:
PM UTC Success
validate recovery window November 18, 2016 8:33:13 PM UTC November 18, 2016 8:33:17
PM UTC Success
Db cross check November 18, 2016 8:33:17 PM UTC November 18, 2016 8:33:23
PM UTC Success
Database Backup November 18, 2016 8:33:23 PM UTC November 18, 2016 8:34:22
PM UTC Success
Backup metadata November 18, 2016 8:34:22 PM UTC November 18, 2016 8:34:22
PM UTC Success
Use the dbcli list-jobs command to display a list of jobs, including the job IDs, status, and
the job
SYNTAX
PARAMETERS
E XAMPLE
ID Description
Created Status
---------------------------------------- ---------------------------------------------------------------
------------ ----------------------------------- ----------
0a362dac-0339-41b5-9c9c-4d229e363eaa Database service creation with db name: db11
November 10, 2016 11:37:54 AM UTC Success
9157cc78-b487-4ee9-9f46-0159f10236e4 Database service creation with db name: jhfpdb
Latestpatch Command
Tip
Note
Use the dbcli describe-latestpatch command show the latest patches applicable to the
DB system and available in Oracle Cloud Infrastructure Object Storage.
This command requires a valid Object Storage credentials configuration. Use the dbcli create-
bmccredential command to create the configuration if you haven't already done so. If the
configuration is missing or invalid, the command fails with the error: Failed to connect to
the object store. Please provide valid details.
For more information about updating the CLI, creating the credentials configuration, and
applying patches, see Patching a DB System.
SYNTAX
PARAMETERS
E XAMPLE
componentType availableVersion
--------------- --------------------
gi 12.1.0.2.161018
db 11.2.0.4.161018
db 12.1.0.2.161018
oak 12.1.2.10.0
Logcleanjob Commands
l dbcli create-logCleanJob
l dbcli describe-logCleanJob
l dbcli list-logCleanJobs
SYNTAX
PARAMETERS
Use the dbcli describe-logCleanJob command to display the summary for a log cleaning
job.
SYNTAX
PARAMETERS
SYNTAX
PARAMETERS
Logspaceusage Command
SYNTAX
PARAMETERS
Netsecurity Commands
The following commands are available to manage network encryption on the DB system:
l dbcli describe-netsecurity
l dbcli update-netsecurity
Use the dbcli describe-netsecurity command to display the current network encryption
setting for a database home.
SYNTAX
PARAMETERS
E XAMPLE
The following command displays the encryption setting for specified database home:
[root@dbsys ~]# dbcli describe-netsecurity -H 16c96a9c-f579-4a4c-a645-8d4d22d6889d
NetSecurity Rules
----------------------------------------------------------------
DatabaseHomeID: 16c96a9c-f579-4a4c-a645-8d4d22d6889d
Role: Server
EncryptionAlgorithms: AES256 AES192 AES128
IntegrityAlgorithms: SHA1
ConnectionType: Required
Role: Client
EncryptionAlgorithms: AES256 AES192 AES128
IntegrityAlgorithms: SHA1
ConnectionType: Required
Use the dbcli update-netsecurity command to update the Oracle Net security
configuration on the DB system.
SYNTAX
PARAMETERS
-H --dbHomeId Defines the database home ID. Use the dbcli list-
dbhomes command to get the dbHomeId.
E XAMPLE
Node Command
Use the dbcli list-nodes command to display a list of nodes, including the node numbers.
SYNTAX
PARAMETERS
E XAMPLE
Objectstoreswift Commands
You can back up a database to an existing bucket in the Oracle Cloud Infrastructure Object
Storage service by using the dbcli create-backup command, but first you'll need to:
1. Create an object store on the DB system, which contains the endpoint and credentials to
access Object Storage, by using the dbcli create-objectstoreswift command.
2. Create a backup configuration that refers to the object store ID and the bucket name by
using the dbcli create-backupconfig command.
3. Associate the backup configuration with the database by using the dbcli update-
database command.
l dbcli create-objectstoreswift
l dbcli describe-objectstoreswift
l dbcli list-objectstoreswifts
SYNTAX
PARAMETERS
https://swiftobjectstorage.<region_
name>.oraclecloud.com/v1
-u --username The user name for the Oracle Cloud Infrastructure user
account, for example:
E XAMPLE
The following command creates an object store and prompts for the Swift password:
[root@dbsys ~]# dbcli create-objectstoreswift -n r2swift -t CompanyABC -u [email protected] -e
https://swiftobjectstorage.<region_name>.oraclecloud.com/v1 -p
Password for Swift:
{
"jobId" : "c565bb71-f67b-4fab-9d6f-a34eae36feb7",
"status" : "Created",
"message" : "Create object store swift",
"reports" : [ ],
"createTimestamp" : "January 19, 2017 11:11:33 AM PST",
"resourceList" : [ {
"resourceId" : "8a0fe039-f5d4-426a-8707-256c612b3a30",
"resourceType" : "ObjectStoreSwift",
"jobId" : "c565bb71-f67b-4fab-9d6f-a34eae36feb7",
"updatedTime" : "January 19, 2017 11:11:33 AM PST"
} ],
"description" : "create object store:biyanr2swift",
"updatedTime" : "January 19, 2017 11:11:33 AM PST"
}
SYNTAX
PARAMETERS
E XAMPLE
Use the dbcli list-objectstoreswifts command to list the object stores on a DB system.
SYNTAX
PARAMETERS
E XAMPLE
Pendingjob Command
SYNTAX
PARAMETERS
Rmanbackupreport Commands
l dbcli create-rmanbackupreport
l dbcli delete-rmanbackupreport
l dbcli describe-rmanbackupreport
l dbcli list-rmanbackupreports
SYNTAX
dbcli create-rmanbackupreport -w {summary|detailed} -rn <name> [-i <db_id>] [-in <db_name>] [-h] [-j]
PARAMETERS
SYNTAX
dbcli delete-rmanbackupreport [-d <db_id>] [-dn <db_name>] [-n <number>] [-i <rpt_id>] [-in <rpt_name>]
[-h] [-j]
PARAMETERS
SYNTAX
PARAMETERS
SYNTAX
PARAMETERS
Schedule Commands
l dbcli describe-schedule
l dbcli list-schedules
l dbcli update-schedule
SYNTAX
PARAMETERS
SYNTAX
PARAMETERS
SYNTAX
dbcli update-schedule -i <id> [-x <expression>] [-t <description>] [-d] [-e] [-h] [-j]
PARAMETERS
Scheduledexecution Command
SYNTAX
PARAMETERS
Server Command
Tip
Use the dbcli update-server command to apply patches to the server components in the DB
system. For more information about applying patches, see Patching a DB System.
SYNTAX
PARAMETERS
E XAMPLES
The following commands update the server and show the output from the update job:
[root@dbsys ~]# dbcli update-server
{
"jobId" : "9a02d111-e902-4e94-bc6b-9b820ddf6ed8",
"status" : "Created",
"reports" : [ ],
"createTimestamp" : "January 19, 2017 09:37:11 AM PST",
"resourceList" : [ ],
"description" : "Server Patching",
"updatedTime" : "January 19, 2017 09:37:11 AM PST"
}
Job details
----------------------------------------------------------------
ID: 9a02d111-e902-4e94-bc6b-9b820ddf6ed8
Description: Server Patching
Status: Running
Created: January 19, 2017 9:37:11 AM PST
Message:
PST Success
Download latest patch metadata January 19, 2017 9:37:11 AM PST January 19, 2017 9:37:11 AM
PST Success
Update System version January 19, 2017 9:37:11 AM PST January 19, 2017 9:37:11 AM
PST Success
Update Patching Repository January 19, 2017 9:37:11 AM PST January 19, 2017 9:38:35 AM
PST Success
oda-hw-mgmt upgrade January 19, 2017 9:38:35 AM PST January 19, 2017 9:38:58 AM
PST Success
Opatch updation January 19, 2017 9:38:58 AM PST January 19, 2017 9:38:58 AM
PST Success
Patch conflict check January 19, 2017 9:38:58 AM PST January 19, 2017 9:42:06 AM
PST Success
apply clusterware patch January 19, 2017 9:42:06 AM PST January 19, 2017 10:02:32
AM PST Success
Updating GiHome version January 19, 2017 10:02:32 AM PST January 19, 2017 10:02:38
AM PST Success
The following command updates node 0 of the server only, with precheck:
# dbcli update-server -n 0 -p
{
"jobId" : "3e2a1e3c-83d3-4101-86b8-4d525f3f8c18",
"status" : "Created",
"message" : null,
"reports" : [ ],
"createTimestamp" : "April 26, 2019 06:07:27 AM UTC",
"resourceList" : [ ],
"description" : "Server Patching Prechecks",
"updatedTime" : "April 26, 2019 06:07:27 AM UTC"
}
System Command
Use the dbcli describe-system command to display details about the system. On a 2-node
RAC DB system, the command provides information about the local node.
SYNTAX
PARAMETERS
TDE Commands
The following commands are available to manage TDE-related items (backup reports, keys,
and wallets):
l dbcli list-tdebackupreports
l dbcli update-tdekey
l dbcli recover-tdewallet
Use the dbcli list-tdebackupreports command to list backup reports for TDE wallets.
SYNTAX
PARAMETERS
-i --dbResid (Optional) Displays the TDE Wallet backup reports for the
specified database resource ID. Use the dbcli list-
databases command to get the database resource ID.
-in -- (Optional) Displays the TDE Wallet backup reports for the
dbResname specified database resource name. Use the dbcli list-
databases command to get the database resource name.
E XAMPLE
Use the dbcli update-tdekey command to update the TDE encryption key inside the TDE
wallet. You can update the encryption key for Pluggable Databases (if -pdbNames are
SYNTAX
PARAMETERS
-t -tagName Defines the TagName used to backup the wallet. The default
is OdaRotateKey.
E XAMPLE
The following command updates the key for pdb1 and pdb2 only:
The following command updates pdb1, pdb2, and the container database:
[root@dbsys ~]# dbcli update-tdekey -dbid ee3eaab6-a45b-4e61-a218-c4ba665503d9 -p -n pdb1,pdb2 -r
SYNTAX
dbcli recover-tdewallet -in <db_name> -tp <password> [-l <location>] [-h] [-j]
PARAMETERS
Admin Commands
Use the dbadmcli manage diagcollect command to collect diagnostic information about a
DB system for troubleshooting purposes, and for working with Oracle Support Services.
SYNTAX
PARAMETERS
Parameter Description
E XAMPLE
DBADMCLI POWER
Note
SYNTAX
PARAMETERS
Parameter Description
name Defines the disk resource name. The resource name format is pd_[0..3]. Use
the dbadmcli show disk command to get the disk resource name.
Use the dbadmcli power disk status command to display the current power status of a
disk.
SYNTAX
PARAMETERS
Parameter Description
name Identifies a specific disk resource name. The resource name format is pd_
[0..3]. For example, pd_01.
E XAMPLE
Use the dbadmcli show controller command to display details of the controller.
SYNTAX
PARAMETER
Parameter Description
controller_ The ID number of the controller. Use the dbadmcli show storage command
id to get the ID.
Use the dbadmcli show disk command to display the status of a single disk or all disks on
the DB system.
SYNTAX
PARAMETERS
Parameter Description
-getlog (Optional) Displays all the SMART log entries for an NVMe disk.
name (Optional) Identifies a specific disk resource name. The resource name
format is pd_[0..3]. If omitted, the command displays information about all
disks on the system.
E XAMPLES
SmartDiskWarnin : 0
SmartTemperatur : 32
State : Online
StateChangeTs : 1467176081
StateDetails : Good
TotalSectors : 6251233968
TypeName : 0
UsrDevName : NVD_S00_S2LHNAAH502855
VendorName : Samsung
gid : 0
mode : 660
uid : 0
Use the dbadmcli show diskgroup command to list configured diskgroups or display a
specific diskgroup configuration.
SYNTAX
PARAMETERS
Parameter Description
E XAMPLES
DiskGroups
----------
DATA
RECO
Use the dbadmcli show env_hw command to display the environment type and hardware
version of the current DB system.
SYNTAX
PARAMETER
Parameter Description
DBADMCLI SHOW FS
SYNTAX
PARAMETER
Parameter Description
Use the dbadmcli show storage command to show the storage controllers, expanders, and
disks.
SYNTAX
PARAMETERS
Parameter Description
E XAMPLE
Id = 0
Pci Slot = 13
Serial Num = S2LHNAAH504431
Vendor = Samsung
Model = MS1PC2DD3ORA3.2T
FwVers = KPYA8R3Q
strId = nvme:25:00.00
Pci Address = 25:00.0
Id = 1
Pci Slot = 12
Serial Num = S2LHNAAH505449
Vendor = Samsung
Model = MS1PC2DD3ORA3.2T
FwVers = KPYA8R3Q
strId = nvme:27:00.00
Pci Address = 27:00.0
Id = 2
Pci Slot = 10
Serial Num = S2LHNAAH503573
Vendor = Samsung
Model = MS1PC2DD3ORA3.2T
FwVers = KPYA8R3Q
strId = nvme:29:00.00
Pci Address = 29:00.0
Id = 3
Pci Slot = 11
Serial Num = S2LHNAAH503538
Vendor = Samsung
Model = MS1PC2DD3ORA3.2T
FwVers = KPYA8R3Q
strId = nvme:2b:00.00
Pci Address = 2b:00.0
DBADMCLI STORDIAG
Use the dbadmcli stordiag command to collect detailed information for each disk or NVM
Express (NVMe).
SYNTAX
PARAMETERS
Parameter Description
name Defines the disk resource name. The resource name format is pd_[0..3].
E XAMPLE
l Use the OLTP templates if your database workload is primarily online transaction
processing (OLTP).
l Use the DSS templates if your database workload is primarily decision support (DSS) or
data warehousing.
l Use the in-memory (IMDB) templates if your database workload can fit in memory, and
can benefit from in-memory performance capabilities.
The following tables describe the templates for each type of workload.
Template CPU SGA PGA Flash Processes Redo Log File Log
Cores (GB) (GB) (GB) Size (GB) Buffer
(MB)
odb1s 1 2 1 6 200 1 16
odb1 1 4 2 12 200 1 16
odb2 2 8 4 24 400 1 16
odb4 4 16 8 48 800 1 32
odb6 6 24 12 72 1200 2 64
Template CPU SGA PGA Processes Redo Log File Log Buffer
Cores (GB) (GB) Size (GB) (MB)
odb1s 1 1 2 200 1 16
odb1 1 2 4 200 1 16
odb2 2 4 8 400 1 16
odb4 4 8 16 800 1 32
odb6 6 12 24 1200 2 64
odb8 8 16 32 1600 2 64
odb10 10 20 40 2000 2 64
odb12 12 24 48 2400 4 64
odb16 16 32 64 3200 4 64
odb20 20 40 80 4000 4 64
odb24 24 48 96 4800 4 64
odb1s 1 2 1 1 200 1 16
odb1 1 4 2 2 200 1 16
odb2 2 8 4 4 400 1 16
odb4 4 16 8 8 800 1 32
odb6 6 24 12 12 1200 2 64
odb8 8 32 16 16 1600 2 64
odb10 10 40 20 20 2000 2 64
odb12 12 48 24 24 2400 4 64
odb16 16 64 32 32 3200 4 64
odb20 20 80 40 40 4000 4 64
odb24 24 96 48 48 4800 4 64
Note
When you provision a virtual machine DB system using the fast provisioning option, the
Available storage (GB) value you specify during provisioning determines the maximum
total storage available through scaling. The following table details the maximum storage
value available through scaling for each setting offered in the provisioning workflow:
256 2560
512 2560
1024 5120
2048 10240
4096 20480
8192 40960
For more information on creating a virtual machine DB system, see Creating Bare Metal and
Virtual Machine DB Systems.
l Makes the base image of the virtual machine DB system compliant with the Oracle Linux
7 STIG
l Embeds certain STIG rules into the system that can be activated after provisioning when
required to meeting security compliance standards
l Categorizes the embedded rules, allowing you to view and monitor the rules in the
following categories:
o Static: Rules included in the base image
o DoD: Rules optionally activated after provisioning when needed to meet U.S.
Department of Defense compliance standards
o Runtime: Rules activated after provisioning when needed. Intended for use by all
users needing to harden security for virtual machine DB systems (including users
outside of the U.S. Department of Defense).
l Provides a rollback capability, allowing you to roll back a DB system to a state with no
configuration modifications made by the script
l Provides a compliance check capability, allowing you to see how many of the scripts
rules are successfully passed by the DB system
The STIG tool is provided for all newly-provisioned virtual machine DB systems. Updated
versions of the STIG tool will be available for download from the Oracle Technology Network
(OTN) . Updated versions of the STIG tool are also provided as available when you update the
DB system agent.
For example:
dbcsstig --fix dod
Command Reference
OPERATIONS
Operation Definition
Parameter
--rollback, -rb Rolls back system configuration changes implemented by the STIG
tool
RULE CATEGORIES
Category Definition
Parameter
static Used to specify rules included in the base image of the virtual
machine DB system
dod Used to specify rules required for compliance with DISA's Oracle
Linux 7 STIG
Category Definition
Parameter
runtime Used to specify rules activated after provisioning for general security
hardening
The time zone that you specify when you create the DB system applies to the host and to the
Oracle Grid Infrastructure (if the system has Grid Infrastructure), and controls the time zone
of the database log files. The time zone of the database itself is not affected, however, the
database’s time zone affects only the timestamp datatype. You can change the database time
zone manually but Oracle recommends that you keep it as UTC (the default) to avoid data
conversion and improve performance when data is transferred among databases. This
configuration is especially important for distributed databases, replication, and export and
import operations.
To specify an alternate time zone (the Select another time zone option), you first select a
value in the Region or country field to narrow the list of time zones to select from in the
Time zone field. In the America/Los_Angeles example, America is the time region and Los_
Angeles is the time zone. The options you see in these two fields roughly correlate with the
time zones supported in both the Java.util.TimeZone class and on the Linux operating system.
If you do not see the time zone you are looking for, try selecting "Miscellaneous" in the
Region and country field.
Tip
If you are using the API and would like to see a list of
supported time zones, you can examine the time zone
options in the Console. These options appear on the
Create DB System page when you show advanced
options after you select a DB system shape.
To change the time zone of the host on DB systems that use Grid
Infrastructure
1. Log on to the host system as root.
2. Stop the CRS stack on all of the compute nodes.
#Grid_Home/bin/crsctl stop crs
3. Run the following commands to check the current time zone and to change it to the time
zone you choose:
$ cat /etc/sysconfig/clock
ZONE="America/New_York"
$ cp -p /etc/sysconfig/clock /etc/sysconfig/clock.20160629
$ vi /etc/sysconfig/clock
ZONE="Europe/Berlin"
$ date
Wed Jun 29 10:35:17 EDT 2016
$ ln -sf /usr/share/zoneinfo/Europe/Berlin /etc/localtime
$ date
Wed Jun 29 16:35:27 CEST 2016
In this example, the time zone was changed from America/New_York to Europe/Berlin.
Tip
To change the time zone of the host on DB systems that use Logical Volume
Manager
Use this procedure for Fast Provisioned virtual machine DB systems, which use Logical
Volume Manager instead of Grid Infrastructure for storage management.
3. Stop all other running processes from the Oracle Database Home.
4. Run the following commands to check the current time zone and to change it to the time
$ vi /etc/sysconfig/clock
ZONE="Europe/Berlin"
$ date
Wed Jun 29 10:35:17 EDT 2016
$ ln -sf /usr/share/zoneinfo/Europe/Berlin /etc/localtime
$ date
Wed Jun 29 16:35:27 CEST 2016
In this example, the time zone was changed from America/New_York to Europe/Berlin.
Tip
5. As Oracle, restart the listener and the database on all of the compute nodes.
lsnrctl start
sqlplus / as sysdba
startup
Note
1. Ensure that you are logged onto the host as root and that the CRS stack is stopped on
all of the compute nodes. See To change the time zone of the host on DB systems that
use Grid Infrastructure.
2. Inspect the current time zone value in the GRID_HOME/crs/install/s_crsconfig_
<node_name>_env.txt file.
$ cat /u01/app/19.0.0.0/grid/crs/install/s_crsconfig_node1_env.txt
#########################################################################
#This file can be used to set values for the NLS_LANG and TZ environment
#variables and to set resource limits for Oracle Clusterware and
#Database processes.
#1. The NLS_LANG environment variable determines the language and
# characterset used for messages. For example, a new value can be
# configured by setting NLS_LANG=JAPANESE_JAPAN.UTF8
#2. The Time zone setting can be changed by setting the TZ entry to
# the appropriate time zone name. For example, TZ=America/New_York
#3. Resource limits for stack size, open files and number of processes
# can be specified by modifying the appropriate entries.
#
#Do not modify this file except as documented above or under the
#direction of Oracle Support Services.
#########################################################################
TZ=UTC
NLS_LANG=AMERICAN_AMERICA.WE8ISO8859P1
CRS_LIMIT_STACK=2048
CRS_LIMIT_OPENFILE=65536
CRS_LIMIT_NPROC=16384
TNS_ADMIN=
3. Modify the time zone value, as applicable. Perform this task for all nodes in the cluster.
4. Restart the CRS stack on all of the compute nodes.
#Grid_Home/bin/crsctl start crs
For more information about changing the time zone of the Grid Infrastructure, see How To
Change Timezone for Grid Infrastructure (Doc ID 1209444.1).
You must restart the database for the change to take effect. For more information, see Setting
the Database Time Zone.
Database Metrics
You can monitor the health, capacity, and performance of your Oracle Cloud Infrastructure
Database service resources by using metrics, alarms, and notifications. For more
information, see Monitoring Overview and Notifications Overview.
This topic describes the metrics emitted by the Database service in the oci_autonomous_
database namespace.
transactions, and so on. You can use metrics data to diagnose and troubleshoot problems with
Autonomous Databases. For a complete list of available metrics for Autonomous Databases,
see Available Metrics: oci_autonomous_database.
To view a default set of metrics charts in the Console, navigate to the Autonomous Database
that you're interested in, and then click Metrics. You also can use the Monitoring service to
create custom queries.
Prerequisites
IAM policies: To monitor resources, 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. The policy must give you access to the monitoring services as well as the
resources being monitored. 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 more information on
user authorizations for monitoring, see the Authentication and Authorization section for the
related service: Monitoring or Notifications.
Database service metrics for Autonomous Databases include the following dimensions:
AUTONOMOUS DBTYPE
The type of Autonomous Database, Autonomous Data Warehouse (ADW) or Autonomous
Transaction Processing (ATP).
DEPLOYMENTTYPE
The Exadata infrastructure type, shared or dedicated. When using the Console to view
default metric charts for multiple Autonomous Databases, you must specify this
dimension.
DISPLAYNAME
REGION
RESOURCEID
RESOURCENAME
In the following table, metrics that are marked with an asterisk (*) can be viewed only on the
Service Metrics page of the Oracle Cloud Infrastructure Console. All metrics can be filtered
by the dimensions discussed in this section. Note that some metrics are only available for
Autonomous Databases using either shared Exadata infrastructure or dedicated Exadata
infrastructure. This is indicated in the Applicable Exadata Infrastructure Type column.
It is
calculated
as the
average
rate of
accumulatio
n of
database
time by
foreground
sessions in
the
database
over the
time
interval.
Also known
as Average
Active
Sessions.
2. Choose the Compartment that contains the Autonomous Database you want to view,
and then click display name of the database to view its details.
3. Under Resources, click Metrics.
The Metrics page displays a default set of charts for the current Autonomous Database.
See Available Metrics: oci_autonomous_database for information about the default
charts.
For more information about monitoring metrics and using alarms, see Monitoring Overview.
For information about notifications for alarms, see Notifications Overview.
Tip
For more information about monitoring metrics and using alarms, see Monitoring Overview.
For information about notifications for alarms, see Notifications Overview.
Note
l ASH Analytics
l SQL Monitoring
l Workload (available for databases using shared Exadata infrastructure)
l Blocking Sessions (available for databases using dedicated Exadata infrastructure)
These tabs, described in detail below, provide information that you can use to analyze the
performance of a selected database, including the following:
l How much of the database is waiting for a resource, such as CPU or disk I/O
l Whether database performance degraded over a given time period and what could be
the likely cause.
l Which specific modules may be causing a load on the system, and where most of
database time is being spent on this module.
l Which SQL statements are the key contributors to changes in database performance,
and which executions are causing them.
l Which user sessions are causing performance bottlenecks.
l Which sessions are currently blocking and if there are outstanding requests for a lock.
The time range selector is displayed at the top of the Performance Hub page. It consists of a
graphically displayed time field as shown in the following illustration. Note that the selected
time range applies to all charts and graphs in the Performance Hub window.
The time range field (#1 in the above illustration) shows database activity in chart form for
the specified Time Range period. The time range is the amount of time being monitored.
Use the Quick Select selector to set the time range. The menu includes five time choices,
Last Hour, Last 8 Hours, Last 24 Hours, Last Week, and Custom. The default time
range is Last Hour. To specify a custom time range, you can also click the Time Range field.
This opens the Custom Time Range dialog, allowing you to specify a custom range.
The Activity graph displays the average number of active sessions broken down by CPU,
User I/O, and Wait. Maximum threads are shown as a red line above the time field.
The sliding box (circled at right in the above illustration) on the time range chart is known as
the time slider. The time slider selects a section of the time range (#2 in the above
illustration) shown in the time range field. It shows the time being analyzed. In the
illustration, the arrows inside the time slider point to the vertical 'handle' elements on the left
and right boundaries of the slider box. The time slider works as follows:
l To change the start and end time of the analysis while keeping the same amount of time
between them, left click anywhere inside the box. Then slide the box left or right along
the time range without changing its size. The selected times are displayed below the
time graph.
l To increase or decrease the length of time being analyzed, left click either one of the
handles and drag it left or right to expand or contract the box.
l To refresh the data in Performance Hub according to the time range chosen, click
Refresh (upper right corner of the window).
Note
Use the Quick Select menu to set the time duration. The menu includes the following five
time choices: Last Hour, Last 8 Hours, Last 24 Hours, Last Week, and Custom. The
default Time Range is Last Hour. The time slider selects the time period of the data displayed
in Performance Hub. The time slider has a different default time period based on the selected
Time Range.
The Time Zone selector is located above the time range field, beside the Quick Select and
Time Range selectors. By default, when you open Performance Hub, the tool displays data in
UTC (Coordinated Universal Time) time. You can use the time zone selector to change the
time zone to either your local web browser time, or the time zone setting of the database you
are working with. When you change the time zone, Performance Hub's reports display data in
your specified time zone.
ASH Analytics Tab
Displayed by default, the ASH (Active Session History) Analytics tab shows ASH analytics
charts to explore ASH data. You use it to drill down into database performance across multiple
dimensions such as Consumer Group, Wait Class, SQL ID, and User Name. In the ASH
Analytics tab, you can select an Average Active Sessions dimension and view the top activity
for that dimension for the selected time period. For more information on ASH, see Active
Session History (ASH) in Oracle Database Concepts.
The SQL Monitoring tab is not displayed by default. To view it, click SQL Monitoring on the
Performance Hub page.
SQL statements are only monitored if they have been running for at least five seconds or if
they are run in parallel. The table in this section displays monitored SQL statement executions
by dimensions including Last Active Time, CPU Time, and Database Time. The table
displays currently running SQL statements and SQL statements that completed, failed, or
were terminated. The columns in the table provide information for monitored SQL statements
including Status, Duration, and SQL ID.
You can also click an SQL ID to go to the corresponding Real-time SQL Monitoring page.
This page provides extra details to help you tune the selected SQL statement.
Workload Tab
The Workload tab in the Performance Hub graphically displays four sets of statistics that you
can use to monitor the database workload and identify spikes and bottlenecks. Each set of
statistics is displayed in a separate region, as described below. The Workload tab supports
Autonomous Databases using Shared Exadata Infrastructure.
The time slider has more functionality in the Workload tab than it does in the Active Session
History and SQL Monitoring tabs. Note the following about the Quick Select time range
options:
l Last Hour, Last 8 Hours, and Last 24 Hours - The charts in the Workload tab display
data for the entire time period of specified time range. A shadowed area is displayed in
each chart that corresponds to the position of the time slider in the time range.
l Last Week - The charts in the Workload tab display data for the selected time period of
the time slider in the time range. There is no shadowed area displayed in this case.
l Custom - The shadowed area display depends on whether the time period is up to and
including 24 hours, or greater than 24 hours.
REGIONS
The tab contains four regions: CPU Statistics, Wait Time Statistics, Workload Profile, and
Sessions. Each region contains one or more charts that indicate the characteristics of the
workload and the distribution of the resources. The data displayed on all the charts is for the
same time period, as selected by the Time Range and time slider at the top of the window.
o User Calls - This option displays the combined number of logons, parses, and
execute calls per second.
o Executions - This option displays the combined number of user and recursive
calls that executed SQL statements per second.
o Transactions - This option displays the combined number of user commits and
user rollbacks per second.
o Parses - This option displays the combined number of hard and soft parses per
second.
o Running Statements - This option displays the number of running SQL
statements, aggregated by consumer group.
o Queued Statements - This option displays the number of queued parallel SQL
statements, aggregated by consumer group.
l The Sessions region contains charts that show the number of current logons and
sessions. It contains a menu that includes the following options:
o Current Logons - This option displays the number of current successful logons.
o Sessions - This option displays the number of sessions.
The Performance Hub blocking sessions tab displays the current blocking and waiting sessions
in a hierarchical display. You can view detailed information about each blocking session, and
can view the sessions blocked by each blocking session. You can also use the tab to inspect or
drill down into the SQL involved, to determine the cause of the blocking. You can perform
several operations in the tab, including killing one or more of the listed sessions to resolve a
waiting session problem. Instructions for the tab functions are located in this topic under
Using the Oracle Cloud Infrastructure Console
The hierarchical display nests waiting sessions underneath the session that they are blocked
by in an easily viewable parent-child relationship. The hierarchy can contain any number of
levels to correctly represent the structure of the sessions involved,
The sessions listed include sessions that are waiting for a resource and sessions that hold a
resource that is being waited on that creates the blocking condition.
The Automatic Workload Repository (AWR) collects, processes, and maintains performance
statistics for problem detection and self-tuning purposes. This data is both in memory and
stored in the database. From the Performance Hub you can generate and download a report of
the gathered data.
An AWR report shows data captured between two points in time (or snapshots). AWR reports
are divided into multiple sections. The content of the report contains the workload profile of
the system for the selected range of snapshots. The HTML report includes links that you can
use to navigate quickly between sections.
l Object statistics that determine both access and usage statistics of database segments
l Time model statistics based on time usage for activities, displayed in the V$SYS_TIME_
MODEL and V$SESS_TIME_MODEL views
l Some of the system and session statistics collected in the V$SYSSTAT and V$SESSTAT
views
l SQL statements that are producing the highest load on the system, based on criteria
such as elapsed time and CPU time
l ASH statistics, representing the history of recent sessions activity
3. In the list of Autonomous Databases, click the display name of the database you want to
analyze using Performance Hub reports.
4. Click Performance Hub.
is selected by default when you use the filtering capabilities to only view the data
for a particular component within a dimension. For information on filtering
Average Active Sessions data, see Filter Average Active Sessions Data.
5. For the dimension selected in the Average Active Sessions drop-down list, you can
further drill down into session details by selecting dimensions in the two sections at the
bottom of the ASH Analytics tab. By default, the following dimensions are selected:
l SQL ID by Consumer Group, which displays the SQL statements with the top
average active sessions activity for consumer groups for the selected time period.
You can right-click the bar charts to sort the SQL statements in ascending or
descending order or click the SQL ID to go the SQL Details page.
l User Session by Consumer Group, which displays the user sessions with the
top average active sessions activity for consumer groups for the selected time
period. You can right-click the bar charts to sort the user sessions in ascending or
descending order or click the user session to go to the User Session page.
3. Use the adjustable time slider box to further narrow down the time period for which
performance data is displayed on the ASH Analytics tab.
4. In the ASH Analytics tab, select a dimension in the Average Active Sessions by drop-
down list. By default, Consumer Group is selected.
The chart is displayed. Each color in the chart denotes a component of the selected
dimension.For example, the Consumer Group dimension has High, Medium, and Low,
which are predefined service names assigned to your Autonomous Database to provide
different levels of concurrency and performance.
5. Click a component in the legend. The selected component is displayed in the Applied
Filters field and the chart is updated to only display data pertaining to that component.
The total activity, which includes all the components of the dimension, is defined by a
black outline and is displayed by default when you filter data.
l If you choose to generate a report from a custom time range, then select Custom
and select start and end times for your range. Click Download.
5. Oracle Database generates a report named AWRReport_date_range.html that
downloads to the default download folder for your browser. View the report after the
download completes.
2. Use the Quick Select selector to set the exact time period for which data is displayed
in the ASH Analytics tables and graphs. By default, the last hour is selected. The time
range is the total amount of time available for analysis.
3. Use the time slider to further narrow down the time period for which performance data
is displayed on the Workload tab. All charts show data for the entire specified time
range if within 24 hours.
4. Click Workload to view the Workload tab. The four regions and their associated charts
are displayed.
l CPU Statistics
The CPU Statistics region contains two charts, CPU Time and CPU Utilization (%).
o To display how much CPU Time is being consumed by the foreground sessions per
second, select CPU Time in the menu in this region. This identifies where the
CPU time is mostly spent in the workload and pinpoints any unusual CPU spikes.
When CPU time is selected optionally click the Maximum Threads check box to
show the maximum CPU time available. This shows the CPU time component of
Average Active Sessions. .
o To display the CPU Utilization (%) chart, select CPU Utilization (%) in the
menu. This chart displays the percentage of CPU time aggregated by consumer
group, as calculated by the resource manager.
l Wait Time Statistics
The Wait Time Statistics region contains one chart that displays the time used in
different wait classes. To see the total average active sessions, select the DB Time
check box. The activities are broken down by the 13 wait classes.
l Workload Profile
To change the metrics displayed in the Workload Profile, click the menu and select the
metric that you want to view.
o Select User Calls to display the combined number of logons, parses, and execute
calls per second.
o Select Executions to display the combined number of user and recursive calls
that executed SQL statements per second.
o Select Transactions to display the combined number of user commits and user
rollbacks per second.
o Select Parses to display the combined number of hard and soft parses per
second
o Select Running Statements to display the number of running SQL statements,
aggregated by consumer group.
o Select Queued Statements to display the number of queued parallel SQL
statements, aggregated by consumer group.
l Sessions
To change the metrics displayed in the Sessions region, click the menu and select the
metric that you want to view:
o Select Current Logons to display the number of current successful logons.
o Select Sessions to display the number of sessions.
Note
Lock This is the lock type for the session. Click the lock type to
display a table with more information about the session lock.
It lists the Lock Type, Lock Mode, Lock Request, Object Type,
Subobject Type, Time, ID1, ID2, Lock Object Address, and
Lock Address of the selected session.
User Session The user session lists the Instance, SID, and Serial number.
Wait Event This is the wait event for the session. Click the wait event to
show additional wait event details.
Blocking Time This is the time that a blocking session has been blocking a
session.
Wait Time This is the time that a session has been waiting.
The minimum wait time works like a filter for the Blocking Sessions information. It sets the
minimum time that a session must wait before it is displayed in the tab. For example, if the
minimum wait time is set to three seconds, and a session has waited only two seconds, it is
not displayed in the table. But if you change the minimum wait time to one second, the
session that waited only two seconds is added to the display.
Note
Killing a Session
1. Click the check box at the left of the session User Name to select a session.
The Kill Session button is enabled.
2. Click Kill Session.
The Kill Session confirmation dialog box is displayed.
3. Click Kill Session to end the session.
1. In the session Lock column, click the name of the lock type (Lock or Exclusive Lock) for
the session.
The Wait Event Details message box is displayed.
2. Note the information in the table and use as needed to determine any action to take.
1. In the session Wait Event column, click the name of the wait event for the selected
session.
The Session Lock Information table is displayed.
2. Note the information in the message box and use as needed to determine any action to
take.
1. In the session User Session column, click the session identifier for the session.
The Performance Hub Session Details page is displayed.
2. Optionally move the time slider to display a specific time range of the session.
3. Use the Session Details page to explore additional details about the session.
1. In the session SQL ID column, click the SQL ID associated with the session.
The Performance Hub SQL Details page is displayed.
2. Optionally move the time slider to display a specific time range of the session.
3. Select one or more of the following tabs, note the information in them, and take any
action needed.
l Summary. This tab displays the SQL Overview and Source details.
l ASH Analytics. This tab displays the SQL average active sessions.
l Execution Statistics. This tab displays the SQL plans and plan details.
l SQL Monitoring. This tab displays information about monitored SQL executions.
l SQL Text. This tab displays the SQL.
Tip
Some of the characteristics and factors to consider when choosing a migration method are:
To determine which migration methods are applicable to your migration scenario, gather the
following information.
After gathering this information, use the “source” and “destination” database versions as your
guide to see which migration methods apply to your migration scenario:
l Migrating from Oracle Database 11g to Oracle Database 11g in the Cloud
l Migrating from Oracle Database 11g to Oracle Database 12c in the Cloud
l Migrating from Oracle Database 12c CDB to Oracle Database 12c in the Cloud
l Migrating from Oracle Database 12c Non-CDB to Oracle Database 12c in the Cloud
1. FastConnect: Provides a secure connection between your existing network and your
virtual cloud network (VCN) over a private physical network instead of the internet. For
more information, see FastConnect.
2. IPSec VPN: Provides a secure connection between a dynamic routing gateway (DRG)
and customer-premise equipment (CPE), consisting of multiple IPSec tunnels. The IPSec
connection is one of the components forming a site-to-site VPN between a VCN and your
on-premises network. For more information, see VPN Connect.
3. Internet gateway: Provides a path for network traffic between your VCN and the
internet. For more information, see Internet Gateway.
Migration Methods
Many methods exist to migrate Oracle databases to the Oracle Cloud Infrastructure Database
service. Which of these methods apply to a given migration scenario depends on several
factors, including the version, character set, and platform endian format of the source and
target databases.
Note
You can migrate an on-premises database to Oracle Cloud Infrastructure by creating a backup
of your on-premises database in Oracle Cloud Infrastructure's Database service.
Oracle provides a Python script to create a backup of your database. The script invokes an API
call to create the backup and then places the backup in Oracle Cloud Infrastructure. You can
then use the Console or the API to create a new database or DB system from that backup.
Backups created using the instructions in this topic appear under Standalone Backups in the
console.
The Python script is bundled as a part of the Oracle Cloud Infrastructure CLI installation.
Oracle provides the migration script and associated files at no cost. Normal Object Storage
charges apply for the storage of your backup in Oracle Cloud Infrastructure.
Compatibility
The scripted migration process is compatible with the following bare metal and virtual
machine DB system configurations:
Oracle Linux
/ Red Hat
Enterprise
7.x
Target Standard
Database Edition
Edition
Enterprise
Edition
Enterprise
Edition -
High
Performance
Enterprise
Edition -
Extreme
Performance
Cluster Single
RAC
Prerequisites
l Outbound internet connectivity for installing Python packages, running yum install, and
access to the Oracle Cloud Infrastructure API and Object Storage.
l RMAN configuration to autobackup controlfile and spfile:
RMAN> CONFIGURE CONTROLFILE AUTOBACKUP ON;
Note
Tip
2. As root, run the CLI installer in the directory you created in step 1. (For example,
/home/oracle/migrate.) See Installing the CLI for instructions on running the installer
script in either Windows or the Bash environment (for MacOS, Linux, and Unix).
The installer installs Python 3.6.0 if either Python 2.7 or Python 3.6 does not exist on the
machine. The installer also installs the Python script required to create and migrate a
standalone backup from an on-premises database.
On Oracle Linux 6, a newer version of Python (such as Python 3.6.0) is usually required.
Use the following instructions to configure Oracle Linux 6 before running the
backup script.
===> Missing native dependencies. Continue and install the following dependencies: gcc, libffi-
devel, python36u-devel, openssl-devel? (Y/n): Y
===> In what directory would you like to place the install? (leave blank to use
'/root/lib/oracle-cli'): /home/oracle/migrate/lib/oracle-cli
===> In what directory would you like to place the 'oci' executable? (leave blank to use
'/root/bin'): /home/oracle/migrate/bin
===> In what directory would you like to place the OCI scripts? (leave blank to use
'/root/bin/oci-cli-scripts'): /home/oracle/migrate/bin/oci-cli-scripts
===> Currently supported optional packages are: ['db (will install cx_Oracle)'] What optional CLI
packages would you like to be installed (comma separated names; press enter if you don't need any
optional packages)?: db
===> Modify profile to update your $PATH and enable shell/tab completion now? (Y/n): Y
If you do not know your API signing key's fingerprint, see How to Get the Key's
Fingerprint.
7. As oracle user (not root), run one of the following sets of commands, depending on the
type of database you are migrating.
For a non-TDE database:
export AD=<destination_availability_domain>
export C=<destination_compartment_OCID>
export ORACLE_SID=<ORACLE_SID>
export ORACLE_HOME=<ORACLE_HOME>
export PATH=$PATH:$ORACLE_HOME/bin
export LC_ALL=en_US.UTF-8
export ORACLE_UNQNAME=<source_DB_unique_name>
rm -rf /home/oracle/migrate/onprem_upload
cd /home/oracle/migrate/bin/oci-cli-scripts/
./create_backup_from_onprem --config-file /home/oracle/migrate/config.txt --display-name
<example_display_name> --availability-domain $AD --edition ENTERPRISE_EDITION_EXTREME_PERFORMANCE
--opc-installer-dir /home/oracle/migrate --tmp-dir /home/oracle/migrate/onprem_upload --
compartment-id $C --rman-password <password>
export AD=<destination_availability_domain>
export C=<destination_compartment_OCID>
export ORACLE_SID=<ORACLE_SID>
export ORACLE_HOME=<ORACLE_HOME>
export PATH=$PATH:$ORACLE_HOME/bin
rm -rf /home/oracle/migrate/onprem_upload
cd /home/oracle/migrate/bin/oci-cli-scripts/
./create_backup_from_onprem --config-file /home/oracle/migrate/config.txt --display-name
<example_display_name> --availability-domain $AD --edition ENTERPRISE_EDITION_EXTREME_PERFORMANCE
--opc-installer-dir /home/oracle/migrate --tmp-dir /home/oracle/migrate/onprem_upload --
compartment-id $C
See the following list of parameters used by the script for more details.
--config-file The path to the oci-cli config file. The default path is as No
follows: ~/.oci/config
--profile The profile in the config file to load. This profile will No
also be used to locate any default parameter values
which have been specified in the OCI CLI-specific
configuration file. The default value is DEFAULT.
--rman- The RMAN password to use for the standalone backup. Required
password The password must have 8 or more characters. if TDE is
not
enabled
The script will produce a standalone backup of your on-premises database in your
Oracle Cloud Infrastructure tenancy. You can check the Console for your backup by
viewing the Standalone Backups page in the Database service, under Bare Metal,
VM, and Exadata.
Tip
8. Create a new database or launch a new DB system using the backup you created in the
preceding step. See Creating a Database for information on creating a new database
from a backup. See Creating Bare Metal and Virtual Machine DB Systems for
information on creating a new DB system from a backup.
The applicability of some of the migration methods depends on the on-premises database’s
character set and platform endian format.
If you have not already done so, determine the database character set of your on-premises
database, and determine the endian format of the platform your on-premises database
resides on. Use this information to help you choose an appropriate method.
Migrating from Oracle Database 11g to Oracle Database 12c in the Cloud
You can migrate Oracle Database 11g databases from on-premises to Oracle Database 12c
databases in the Database service using several different methods.
The applicability of some of the migration methods depends on the on-premises database’s
version, database character set and platform endian format.
If you have not already done so, determine the database version and database character set
of your on-premises database, and determine the endian format of the platform your on-
premises database resides on. Use this information to help you choose an appropriate
method.
Migrating from Oracle Database 12c CDB to Oracle Database 12c in the
Cloud
You can migrate Oracle Database 12c CDB databases from on-premises to Oracle Database
12c databases in the Oracle Cloud Infrastructure Database service using several different
methods.
The applicability of some of the migration methods depends on the on-premises database’s
character set and platform endian format.
If you have not already done so, determine the database character set of your on-premises
database, and determine the endian format of the platform your on-premises database
resides on. Use this information to help you choose an appropriate method.
For the steps this method entails, see Data Pump Transportable Tablespace.
l RMAN Transportable Tablespace with Data Pump
This method can be used only if the on-premises platform is little endian, and the
database character sets of your on-premises database and the Oracle Cloud
Infrastructure Database service database are compatible.
For the steps this method entails, see RMAN Transportable Tablespace with Data Pump.
l RMAN CONVERT Transportable Tablespace with Data Pump
This method can be used only if the database character sets of your on-premises
database and the Database database are compatible.
This method is similar to the Data Pump Transportable Tablespace method, with the
addition of the RMAN CONVERT command to enable transport between platforms with
different endianness. Query V$TRANSPORTABLE_PLATFORM to determine if the on-
premises database platform supports cross-platform tablespace transport and to
determine the endian format of the platform. The Database service platform is little-
endian format.
For the steps this method entails, see RMAN CONVERT Transportable Tablespace with
Data Pump.
l RMAN Cross-Platform Transportable Tablespace Backup Sets
This method can be used only if the database character sets of your on-premises
database and the Database service database are compatible.
For the steps this method entails, see RMAN Cross-Platform Transportable Tablespace
Backup Sets.
l Data Pump Full Transportable
This method can be used only if the database character sets of your on-premises
database and the Database service database are compatible.
For the steps this method entails, see Data Pump Full Transportable.
l Unplugging/Plugging (CDB)
This method can be used only if the on-premises platform is little endian, and the on-
premises database and Database database have compatible database character sets
and national character sets.
The applicability of some of the migration methods depends on the on-premises database’s
character set and platform endian format.
If you have not already done so, determine the database character set of your on-premises
database, and determine the endian format of the platform your on-premises database
resides on. Use this information to help you choose an appropriate method.
For the steps this method entails, see SQL Developer and SQL*Loader to Migrate
Selected Objects.
l SQL Developer and INSERT Statements to Migrate Selected Objects
You can use SQL Developer to create a cart into which you add selected objects to be
loaded into your Oracle Database 12c database on the cloud. In this method, you use
SQL INSERT statements to load the data into your cloud database.
For the steps this method entails, see SQL Developer and INSERT Statements to Migrate
Selected Objects.
1. On the on-premises database host, invoke Data Pump Export and export the on-
premises database.
2. Use a secure copy utility to transfer the dump file to the Database service compute
node.
3. On the Database service compute node, invoke Data Pump Import and import the data
into the database.
4. After verifying that the data has been imported successfully, you can delete the dump
file.
For information about Data Pump Import and Export, see these topics:
l "Data Pump Export Modes" in Oracle Database Utilities for Release 12.2, 12.1 or 11.2.
l "Data Pump Import Modes" in Oracle Database Utilities for Release 12.2, 12.1 or 11.2.
This example illustrates a schema mode export and import. The same general procedure
applies for a full database, tablespace, or table export and import.
1. On the on-premises database host, invoke Data Pump Export to export the schemas.
a. On the on-premises database host, create an operating system directory to use
for the on-premises database export files.
$ mkdir /u01/app/oracle/admin/orcl/dpdump/for_cloud
b. On the on-premises database host, invoke SQL*Plus and log in to the on-premises
database as the SYSTEM user.
$ sqlplus system
Enter password: <enter the password for the SYSTEM user>
2. Use a secure copy utility to transfer the dump file to the Database service compute
node.
In this example the dump file is copied to the /u01 directory. Choose the appropriate
location based on the size of the file that will be transferred.
a. On the Database service compute node, create a directory for the dump file.
$ mkdir /u01/app/oracle/admin/ORCL/dpdump/from_onprem
b. Before using the scp command to copy the export dump file, make sure the SSH
private key that provides access to the Database service compute node is
available on your on-premises host.
c. On the on-premises database host, use the SCP utility to transfer the dump file to
the Databaseservice compute node.
$ scp –i private_key_file \
/u01/app/oracle/admin/orcl/dpdump/for_cloud/expdat.dmp \
oracle@IP_address_DBaaS_VM:/u01/app/oracle/admin/ORCL/dpdump/from_onprem
3. On the Database service compute node, invoke Data Pump Import and import the data
into the database.
a. On the Database service compute node, invoke SQL*Plus and log in to the
database as the SYSTEM user.
$ sqlplus system
Enter password: <enter the password for the SYSTEM user>
c. If they do not exist, create the tablespace(s) for the objects that will be imported.
d. Exit from SQL*Plus.
e. On the Database service compute node, invoke Data Pump Import and connect to
the database. Import the data into the database.
impdp system SCHEMAS=fsowner DIRECTORY=dp_from_onprem
4. After verifying that the data has been imported successfully, you can delete the
expdat.dmp file.
You can use the Data Pump full transportable method to copy an entire database from your
on-premises host to the database on a Database service database deployment.
To migrate an Oracle Database 11g on-premises database to the Oracle Database 12c
database on a Database service database deployment using the Data Pump full transportable
method, you perform these tasks:
1. On the on-premises database host, prepare the database for the Data Pump full
transportable export by placing the user-defined tablespaces in READ ONLY mode.
2. On the on-premises database host, invoke Data Pump Export to perform the full
transportable export.
3. Use a secure copy utility to transfer the Data Pump Export dump file and the datafiles
for all of the user-defined tablespaces to the Database service compute node.
4. Set the on-premises tablespaces back to READ WRITE.
5. On the Database service compute node, prepare the database for the tablespace import.
6. On the Database service compute node, invoke Data Pump Import and connect to the
database.
7. After verifying that the data has been imported successfully, you can delete the dump
file.
1. On the source database host, prepare the database for the Data Pump full transportable
export.
a. On the source database host, create a directory in the operating system to use for
the source export.
$ mkdir /u01/app/oracle/admin/orcl/dpdump/for_cloud
b. On the source database host, invoke SQL*Plus and log in to the source database
as the SYSTEM user.
$ sqlplus system
Enter password: <enter the password for the SYSTEM user>
d. Determine the name(s) of the tablespaces and data files that belong to the user-
defined tablespaces by querying DBA_DATA_FILES. These files will also be listed in
the export output.
SQL> SELECT tablespace_name, file_name FROM dba_data_files;
TABLESPACE_NAME FILE_NAME
--------------- --------------------------------------------------
USERS /u01/app/oracle/oradata/orcl/users01.dbf
UNDOTBS1 /u01/app/oracle/oradata/orcl/undotbs01.dbf
SYSAUX /u01/app/oracle/oradata/orcl/sysaux01.dbf
SYSTEM /u01/app/oracle/oradata/orcl/system01.dbf
EXAMPLE /u01/app/oracle/oradata/orcl/example01.dbf
FSDATA /u01/app/oracle/oradata/orcl/fsdata01.dbf
FSINDEX /u01/app/oracle/oradata/orcl/fsindex01.dbf
SQL>
e. On the source database host, set all tablespaces that will be transported (the
transportable set) to READ ONLY mode.
SQL> ALTER TABLESPACE example READ ONLY;
Tablespace altered.
SQL> ALTER TABLESPACE fsindex READ ONLY;
Tablespace altered.
SQL> ALTER TABLESPACE fsdata READ ONLY;
Tablespace altered.
SQL> ALTER TABLESPACE users READ ONLY;
Tablespace altered.
SQL>
3. Use a secure copy utility to transfer the Data Pump Export dump file and the datafiles
for all of the user-defined tablespaces to the Database service compute node.
In this example the dump file is copied to the /u01 directory. Choose the appropriate
location based on the size of the file that will be transferred.
a. On the Database service compute node, create a directory for the dump file.
$ mkdir /u01/app/oracle/admin/ORCL/dpdump/from_source
b. Before using the scp utility to copy files, make sure the SSH private key that
provides access to the Database service compute node is available on your source
host.
c. On the source database host, use the scp utility to transfer the dump file and all
datafiles of the transportable set to the Database service compute node.
$ scp -i private_key_file \
/u01/app/oracle/admin/orcl/dpdump/for_cloud/expdat.dmp \
oracle@compute_node_IP_address:/u01/app/oracle/admin/ORCL/dpdump/from_source
$ scp -i private_key_file \
/u01/app/oracle/oradata/orcl/example01.dbf \
oracle@compute_node_IP_address:/u02/app/oracle/oradata/ORCL/PDB2
$ scp -i private_key_file \
/u01/app/oracle/oradata/orcl/fsdata01.dbf \
oracle@compute_node_IP_address:/u02/app/oracle/oradata/ORCL/PDB2
$ scp -i private_key_file \
/u01/app/oracle/oradata/orcl/fsindex01.dbf \
oracle@compute_node_IP_address:/u02/app/oracle/oradata/ORCL/PDB2
$ scp -i private_key_file \
/u01/app/oracle/oradata/orcl/users01.dbf \
oracle@compute_node_IP_address:/u02/app/oracle/oradata/ORCL/PDB2
6. On the Database service compute node, invoke Data Pump Import and connect to the
PDB.
Import the data into the database using the TRANSPORT_DATAFILES option.
$ impdp system@PDB2 FULL=y DIRECTORY=dp_from_source \
TRANSPORT_
DATAFILES='/u02/app/oracle/oradata/ORCL/PDB2/example01.dbf',\
'/u02/app/oracle/oradata/ORCL/PDB2/fsdata01.dbf',\
'/u02/app/oracle/oradata/ORCL/PDB2/fsindex01.dbf,'\
'/u02/app/oracle/oradata/ORCL/PDB2/users01.dbf'
7. After verifying that the data has been imported successfully, you can delete the
expdat.dmp dump file.
1. On the on-premises database host, prepare the database for the Data Pump
transportable tablespace export.
2. On the on-premises database host, invoke Data Pump Export to perform the
transportable tablespace export.
3. Use a secure copy utility to transfer the Data Pump Export dump file and the tablespace
datafiles to the Database service compute node.
4. Set the on-premises tablespaces back to READ WRITE.
5. On the Databaseservice compute node, prepare the database for the tablespace import.
6. On the Database service compute node, invoke Data Pump Import and connect to the
database.
7. Set the tablespaces on the Database service database to READ WRITE mode.
8. After verifying that the data has been imported successfully, you can delete the dump
file.
1. On the on-premises database host, prepare the database for the Data Pump
transportable tablespace export.
a. On the on-premises database host, create a directory in the operating system to
use for the on-premises export.
mkdir /u01/app/oracle/admin/orcl/dpdump/for_cloud
b. On the on-premises database host, invoke SQL*Plus and log in to the on-premises
database as the SYSTEM user.
sqlplus system
Enter password: <enter the password for the SYSTEM user>
d. Determine the name(s) of the datafiles that belong to the FSDATA and FSINDEX
tablespaces by querying DBA_DATA_FILES. These files will also be listed in the
export output.
SQL> SELECT file_name FROM dba_data_files
2 WHERE tablespace_name = 'FSDATA';
FILE_NAME
-----------------------------------------------------------------
/u01/app/oracle/oradata/orcl/fsdata01.dbf
FILE_NAME
-----------------------------------------------------------------
/u01/app/oracle/oradata/orcl/fsindex01.dbf
e. On the on-premises database host, set all tablespaces that will be transported
(the transportable set) to READ ONLY mode.
3. Use a secure copy utility to transfer the Data Pump Export dump file and the tablespace
datafiles to the Database service compute node.
In this example the dump file is copied to the /u01 directory. Choose the appropriate
location based on the size of the file that will be transferred.
a. On the Database service compute node, create a directory for the dump file.
mkdir /u01/app/oracle/admin/ORCL/dpdump/from_onprem
b. Before using the scp utility to copy files, make sure the SSH private key that
provides access to the Database service compute node is available on your on-
premises host.
c. On the on-premises database host, use the scp utility to transfer the dump file
and all datafiles of the transportable set to the Database service compute node.
scp -i private_key_file \
/u01/app/oracle/admin/orcl/dpdump/for_cloud/expdat.dmp \
oracle@IP_address_DBaaS_VM:/u01/app/oracle/admin/ORCL/dpdump/from_onprem
a. On the Database service compute node, invoke SQL*Plus and log in to the
database as the SYSTEM user.
b. Create a directory object in the Database service database.
SQL> CREATE DIRECTORY dp_from_onprem AS '/u01/app/oracle/admin/ORCL/dpdump/from_onprem';
c. If the owners of the objects that will be imported do not exist in the database,
create them before performing the import. The transportable tablespace mode of
import does not create the users.
SQL> CREATE USER fsowner
2 PROFILE default
3 IDENTIFIED BY fspass
4 TEMPORARY TABLESPACE temp
5 ACCOUNT UNLOCK;
6. On the Database service compute node, invoke Data Pump Import and connect to the
database.
Import the data into the database using the TRANSPORT_DATAFILES option.
impdp system DIRECTORY=dp_from_onprem \
TRANSPORT_DATAFILES='/u02/app/oracle/oradata/ORCL/fsdata01.dbf', \
'/u02/app/oracle/oradata/ORCL/fsindex01.dbf'
7. Set the tablespaces on the Database service database to READ WRITE mode.
a. Invoke SQL*Plus and log in as the SYSTEM user.
b. Set the FSDATA and FSINDEX tablespaces to READ WRITE mode.
You can use the remote cloning method to copy a PDB from your on-premises Oracle
Database 12c database to a PDB in an Oracle Database 12c database on the Database service.
Migration Tasks
To migrate an Oracle Database 12c PDB to a PDB in a Database service database deployment
using the remote cloning method, you perform these tasks:
1. On the on-premises database host, invoke SQL*Plus and close the on-premises PDB and
then reopen it in READ ONLY mode.
2. On the Database service compute node, invoke SQL*Plus and create a database link that
enables a connection to the on-premises database.
3. On the Database service compute node, execute the CREATE PLUGGABLE DATABASE
command to clone the on-premises PDB.
4. On the Database compute node, open the new PDB by executing the ALTER PLUGGABLE
DATABASE OPEN command.
5. Optionally, on the on-premises database host invoke SQL*Plus and set the on-premises
PDB back to READ WRITE mode.
For more information, see "Cloning a Remote PDB or Non-CDB" in Oracle Database
Administrator's Guide for Release 12.2 or 12.1.
You can use the remote cloning method to copy an Oracle Database 12c non-CDB on-premises
database to a PDB in an Oracle Database 12c database on the Databaseservice.
Migration Tasks
1. On the on-premises database host, invoke SQL*Plus and set the on-premises database
to READ ONLY mode.
2. On the Database service compute node, invoke SQL*Plus and create a database link that
enables a connection to the on-premises database.
3. On the Database service compute node, execute the CREATE PLUGGABLE DATABASE
command to clone the on-premises non-CDB database.
4. On the Database service compute node, execute the $ORACLE_
HOME/rdbms/admin/noncdb_to_pdb.sql script.
5. On the Database service compute node, open the new PDB by executing the ALTER
PLUGGABLE DATABASE OPEN command.
6. Optionally, on the on-premises database host invoke SQL*Plus and set the on-premises
database back to READ WRITE mode.
For more information, see "Cloning a Remote PDB or Non-CDB" in Oracle Database
Administrator's Guide for Release 12.2 or 12.1.
To migrate an Oracle Database 12c PDB to a PDB in an Oracle Database 12c database on a
Database service deployment using the RMAN cross-platform transportable PDB method, you
perform these tasks:
1. On the on-premises database host, invoke SQL*Plus and close the on-premises PDB.
2. On the on-premises database host, execute the ALTER PLUGGABLE DATABASE UNPLUG
command to generate an XML file containing the list of datafiles that will be plugged in
on the cloud database.
3. On the on-premises database host, invoke RMAN and connect to the root. Execute the
BACKUP FOR TRANSPORT PLUGGABLE DATABASE command.
4. Use a secure copy utility to transfer the XML file and the backup set to the Database
service compute node.
5. On the Database service compute node, invoke RMAN and connect to the root. Execute
the RESTORE ALL FOREIGN DATAFILES command.
6. the Database service compute node, invoke SQL*Plus and connect to the root. Execute
the CREATE PLUGGABLE DATABASE command.
7. the Database service compute node, execute the ALTER PLUGGABLE DATABASE OPEN
command.
For more information, see " Performing Cross-Platform Data Transport in CDBs and PDBs" in
Oracle Database Backup and Recovery User's Guide for Release 12.2 or 12.1.
Note
To migrate Oracle Database 12c on-premises tablespaces to an Oracle Database 12c database
on a Database service deployment using the RMAN cross-platform transportable backup sets
method, you perform these tasks:
1. On the on-premises database host, prepare the database by placing the user-defined
tablespaces that you intend to transport in READ ONLY mode.
2. On the on-premises database host, invoke RMAN and use the BACKUP command with the
TO PLATFORM or FOR TRANSPORT clause and the DATAPUMP clause to create a backup set
for cross-platform transport. See in "BACKUP" in Oracle Database Backup and Recovery
Reference for Release 12.2 or 12.1 for more information on the BACKUP command.
3. Use a secure copy utility to transfer the backup sets, including the Data Pump export
dump file, to the Database service compute node.
4. Set the on-premises tablespaces back to READ WRITE.
5. On the Database service compute node, prepare the database by creating the required
schemas.
6. On the Database service compute node, invoke RMAN and use the RESTORE command
with the foreignFileSpec subclause to restore the cross-platform backup.
7. On the Database service compute node, set the tablespaces on the database to READ
WRITE mode.
For more information, see "Overview of Cross-Platform Data Transport Using Backup Sets" in
Oracle Database Backup and Recovery User’s Guide for Release 12.2 or 12.1.
1. On the on-premises database host, prepare the database by creating a directory for the
export dump file and placing the user-defined tablespaces that you intend to transport in
READ ONLY mode..
a. On the on-premises database host, create a directory in the operating system to
use for the export dump.
mkdir /u01/app/oracle/admin/orcl/dpdump/for_cloud
b. On the on-premises data host, invoke SQL*Plus and log in to the PDB as the
SYSTEM user..
sqlplus system@pdb_servicename
Enter password: enter the password for the SYSTEM user
d. On the on-premises database host, set all tablespaces that will be transported
(the transportable set) to READ ONLY mode.
SQL> ALTER TABLESPACE fsindex READ ONLY;
SQL> ALTER TABLESPACE fsdata READ ONLY;
mkdir /u01/app/oracle/admin/orcl/rman_transdest
b. Invoke RMAN and log in as a user that has been granted the SYSDBA or SYSBACKUP
privilege.
rman target username@pdb_servicename
3. Use a secure copy utility to transfer the backup set, including the Data Pump export
dump file, to the Database service compute node.
a. On the Database service compute node, create a directory for the backup set and
dump file.
mkdir /tmp/from_onprem
b. Before using the scp command to copy files, make sure the SSH private key that
provides access to the Database service compute node is available on your on-
premises host.
c. On the on-premises database host, use the SCP utility to transfer the backup set
and the dump file to the Database service compute node.
scp -i private_key_file \
/u01/app/oracle/admin/orcl/rman_transdest/fs_tbs.bck \
oracle@IP_address_DBaaS_VM:/tmp/from_onprem
$ scp -i private_key_file \
/u01/app/oracle/admin/orcl/rman_transdest/fs_tbs.dmp \
oracle@IP_address_DBaaS_VM:/tmp/from_onprem
6. On the Database service compute node, invoke RMAN and use the RESTORE command
with the foreignFileSpec subclause to restore the cross-platform backup.
a. Create an operating system directory for the Data Pump Dump file.
mkdir /tmp/from_onprem
b. Invoke RMAN and log in to the PDB as a user that has been granted the SYSDBA or
SYSBACKUP privilege.
rman target username@pdb_servicename
You can use this method to eliminate placing the tablespaces in READ ONLY mode, as required
by the Data Pump Transportable Tablespace method.
1. On the on-premises database host, invoke RMAN and create the transportable
tablespace set.
2. Use a secure copy utility to transfer the Data Pump Export dump file and the tablespace
datafiles to the Database service compute node.
3. On the Database service compute node, prepare the database for the tablespace import.
4. On the Database service compute node, invoke Data Pump Import and connect to the
database. Import the data into the database using the TRANSPORT_DATAFILES option.
5. After verifying that the data has been imported successfully, you can delete the dump
file.
1. On the on-premises database host, invoke RMAN and create the transportable
tablespace set.
a. On the on-premises database host, create an operating system directory for the
datafiles.
mkdir /u01/app/oracle/admin/orcl/rman_transdest
b. On the on-premises data host, create an operating system directory for the RMAN
auxiliary instance files.
mkdir /u01/app/oracle/admin/orcl/rman_auxdest
c. Invoke RMAN and log in as the SYSTEM user. Enter the password for the SYSTEM
user when prompted.
rman target system
DESTINATION and view the files that were created by the TRANSPORT TABLESPACE
operation.
cd /u01/app/oracle/admin/orcl/rman_transdest
$ ls
dmpfile.dmp fsdata01.dbf fsindex01.dbf impscrpt.sql
2. Use a secure copy utility to transfer the Data Pump Export dump file and the tablespace
datafiles to the Database service compute node.
In this example the dump file is copied to the /u01 directory. Choose the appropriate
location based on the size of the file that will be transferred.
a. On the Database service compute node, create a directory for the dump file.
mkdir /u01/app/oracle/admin/ORCL/dpdump/from_onprem
b. Before using the scp command to copy files, make sure the SSH private key that
provides access to the Database service compute node is available on your on-
premises host.
c. On the on-premises database host, use the SCP utility to transfer the dump file
and all datafiles of the transportable set to the Database service compute node.
scp -i private_key_file \
/u01/app/oracle/admin/orcl/rman_transdest/dmpfile.dmp \
oracle@IP_address_DBaaS_VM:/u01/app/oracle/admin/ORCL/dpdump/from_onprem
$ scp -i private_key_file \
/u01/app/oracle/admin/orcl/rman_transdest/fsdata01.dbf \
oracle@IP_address_DBaaS_VM:/u02/app/oracle/oradata/ORCL
$ scp -i private_key_file \
/u01/app/oracle/admin/orcl/rman_transdest/fsindex01.dbf \
oracle@IP_address_DBaaS_VM:/u02/app/oracle/oradata/ORCL
3. On the Database service compute node, prepare the database for the tablespace import.
a. On the Database service compute node, invoke SQL*Plus and log in to the
database as the SYSTEM user.
b. Create a directory object in the Database service database.
c. If the owners of the objects that will be imported do not exist in the database,
create them before performing the import. The transportable tablespace mode of
import does not create the users.
SQL> CREATE USER fsowner
2 PROFILE default
3 IDENTIFIED BY fspass
4 TEMPORARY TABLESPACE temp
5 ACCOUNT UNLOCK;
4. On the Database service compute node, invoke Data Pump Import and connect to the
database.
Import the data into the database using the TRANSPORT_DATAFILES option.
impdp system DIRECTORY=dp_from_onprem DUMPFILE='dmpfile.dmp' \
TRANSPORT_DATAFILES='/u02/app/oracle/oradata/ORCL/fsdata01.dbf', \
'/u02/app/oracle/oradata/ORCL/fsindex01.dbf'
5. After verifying that the data has been imported successfully, you can delete the
dmpfile.dmp dump file.
This method is similar to the Data Pump Transportable Tablespace method, with the addition
of the RMAN CONVERT command to enable transport between platforms with different
endianness. Query V$TRANSPORTABLE_PLATFORM to determine if the on-premises database
platform supports cross-platform tablespace transport and to determine the endian format of
the platform. The Database service platform is little-endian format.
1. On the on-premises database host, prepare the database for the Data Pump
transportable tablespace export.
2. On the on-premises database host, invoke Data Pump Export to perform the
transportable tablespace export.
3. On the on-premises database host, invoke RMAN and use the CONVERT TABLESPACE
command to convert the tablespace datafile to the Database service platform format.
Refer to the Oracle Database Backup and Recovery Reference for more information on
the CONVERT command.
4. Use a secure copy utility to transfer the Data Pump Export dump file and the converted
tablespace datafiles to the Database service compute node.
5. Set the on-premises tablespaces back to READ WRITE.
6. On the Database service compute node, prepare the database for the tablespace import.
7. On the Database service compute node, invoke Data Pump Import and connect to the
database.
8. On the Database service compute node, set the tablespaces in the database to READ
WRITE mode.
9. After verifying that the data has been imported successfully, you can delete the dump
file.
1. On the on-premises database host, prepare the database for the Data Pump
transportable tablespace export.
a. On the on-premises database host, create a directory in the operating system to
use for the on-premises export.
mkdir /u01/app/oracle/admin/orcl/dpdump/for_cloud
b. On the on-premises database host, invoke SQL*Plus and log in to the on-premises
d. On the on-premises database host, set all tablespaces that will be transported
(the transportable set) to READ ONLY mode.
SQL> ALTER TABLESPACE fsindex READ ONLY;
Tablespace altered.
SQL> ALTER TABLESPACE fsdata READ ONLY;
Tablespace altered.
3. On the on-premises database host, invoke RMAN and use the CONVERT TABLESPACE
command to convert the tablespace datafile to the Database service platform format.
a. Invoke RMAN.
rman target /
b. Execute the RMAN CONVERT TABLESPACE command to convert the datafiles and
store the converted files in a temporary location on the on-premises database
host.
RMAN> CONVERT TABLESPACE fsdata, fsindex
2> TO PLATFORM 'Linux x86 64-bit'
3> FORMAT '/tmp/%U ';
…
c. Take note of the names of the converted files. You will copy these files to the
Database service compute node in the next step.
d. Exit RMAN.
4. Use a secure copy utility to transfer the Data Pump Export dump file and the converted
tablespace datafiles to the Database service compute node.
In this example the dump file is copied to the /u01 directory. Choose the appropriate
location based on the size of the file that will be transferred.
a. On the Databaseservice compute node, create a directory for the dump file.
mkdir /u01/app/oracle/admin/ORCL/dpdump/from_onprem
b. Before using the scp command to copy files, make sure the SSH private key that
provides access to the Database service compute node is available on your on-
premises host.
c. On the on-premises database host, use the scp utility to transfer the dump file
and all data files of the transportable set to the Database service compute node.
scp -i private_key_file \
/u01/app/oracle/admin/orcl/dpdump/for_cloud/expdat.dmp \
oracle@IP_address_DBaaS_VM:/u01/app/oracle/admin/ORCL/dpdump/from_onprem
$ scp -i private_key_file \
/tmp/data_D-ORCL_I-1410251631_TS-FSDATA_FNO-6_0aqc9un3 \
oracle@IP_address_DBaaS_VM:/u02/app/oracle/oradata/ORCL/fsdata01.dbf
$ scp -i private_key_file \
/tmp/data_D-ORCL_I-1410251631_TS-FSINDEX_FNO-7_0bqc9un6 \
oracle@IP_address_DBaaS_VM:/u02/app/oracle/oradata/ORCL/fsindex01.dbf
a. On the Database service compute node, invoke SQL*Plus and log in to the
database as the SYSTEM user.
b. Create a directory object in the Database service database.
SQL> CREATE DIRECTORY dp_from_onprem AS '/u01/app/oracle/admin/ORCL/dpdump/from_onprem';
c. If the owners of the objects that will be imported do not exist in the database,
create them before performing the import. The transportable tablespace mode of
import does not create the users.
SQL> CREATE USER fsowner
2 PROFILE default
3 IDENTIFIED BY fspass
4 TEMPORARY TABLESPACE temp
5 ACCOUNT UNLOCK;
7. On the Database service compute node, invoke Data Pump Import and connect to the
database.
Import the data into the Database service database using the TRANSPORT_DATAFILES
option
impdp system DIRECTORY=dp_from_onprem \
TRANSPORT_DATAFILES='/u02/app/oracle/oradata/ORCL/fsdata01.dbf', \
'/u02/app/oracle/oradata/ORCL/fsindex01.dbf'
8. On the Database service compute node, set the tablespaces in the database to READ
WRITE mode.
Note
Prerequisites
l The source database name, database unique name, listener port, service name,
database home patch level, and the password for SYS.
l A copy of the sqlpatch directory from the source database home. This is required for
rollback in case the target DB system does not include these patches.
l If the source database is configured with Transparent Data Encryption (TDE), you'll
need a backup of the wallet and the wallet password to allow duplication of a database
with encrypted data.
When migrating a source database to an existing target database, Oracle recommends that
you patch the source environment to the same database bundle patch level as the target
database home. If the source environment has an interim patch (previously known as a "one-
off" patch) that includes a sqlpatch component, and that sqlpatch is missing from the target
environment (or a different cumulative patch is applied), the interim patch should be rolled
back in the source environment before the migration, if possible.
Tip
l A target DB system that supports the same database edition as the source database
edition. When you launch a DB system, an initial database is created on it. If necessary,
you can delete that database and create a new one by using the dbcli command line
interface. For more information on creating a DB system, see Creating Bare Metal and
Virtual Machine DB Systems. For information about creating a database with the DBCLI,
If you need to roll back interim patches in the target environment so that the patch level
matches that of the source environment, copy the source DB $ORACLE_
HOME/sqlpatch/<patch_number> directory to the target database home.
1. Make sure the source DB system is reachable from the target DB system. You should be
able to SSH between the two hosts.
2. On the target host, use the TNSPING utility to make sure the source host listener port
works. For example:
tnsping <source_host>:1521
3. On the target host, use Easy Connect to verify the connection to the source database:
<host>:<port>/<service_name>
For example:
sqlplus [email protected]:1521/proddb
5. Make sure at least one archivelog has been created on the source database, otherwise,
the RMAN duplication will fail with an error.
6. If the source database uses wallets, back up the password-based wallet and copy it to
the standard location in the DB system:
/opt/oracle/dcs/commonstore/wallets/tde/<db_unique_name>/
7. Make sure the compatibility parameters in the source database are set to at least:
l 18.0.0.0.0 for an 18.1.0.0 database
l 12.1.0.2.0 for a 12.1.0.2 or a 12.2.0.1 database
l 11.2.0.4.0 for an 11.2.0.4 database
2. Log in as opc and then sudo to the root user. Use sudo su - with a hyphen to invoke the
root user's profile, which will set the PATH to the dbcli directory
(/opt/oracle/dcs/bin).
login as: opc
3. Use the dbcli create-dbstorage to set up directories for DATA, RECO, and REDO storage.
The following example creates 10GB of ACFS storage for the tdetest database.
[root@dbsys ~]# dbcli create-dbstorage --dbname tdetest --dataSize 10 --dbstorage ACFS
Note
4. Use the dbcli list-dbstorages command to list the storage ID. You'll need the ID for the
next step.
[root@dbsys ~]# dbcli list-dbstorages
ID Type DBUnique Name Status
---------------------------------------- ------ -------------------- ----------
9dcdfb8e-e589-4d5f-861a-e5ba981616ed Acfs tdetest Configured
5. Use the dbcli describe-dbstorage command with the storage ID from the previous step
to list the DATA, RECO and REDO locations.
[root@dbsys ~]# dbcli describe-dbstorage --id 9dcdfb8e-e589-4d5f-861a-e5ba981616ed
DBStorage details
----------------------------------------------------------------
ID: 9dcdfb8e-e589-4d5f-861a-e5ba981616ed
DB Name: tdetest
DBUnique Name: tdetest
DB Resource ID:
Storage Type: Acfs
DATA Location: /u02/app/oracle/oradata/tdetest
RECO Location: /u03/app/oracle/fast_recovery_area/
REDO Location: /u03/app/oracle/redo/
State: ResourceState(status=Configured)
Created: August 24, 2016 5:25:38 PM UTC
UpdatedTime: August 24, 2016 5:25:53 PM UTC
Note the locations. You'll use them later to set the db_create_file_dest, db_create_
online_log_dest, and db_recovery_file_dest parameters for the database.
Choosing an ORACLE_HOME
Decide which ORACLE_HOME to use for the database restore and then switch to that home
with the correct ORACLE_BASE, ORACLE_HOME, and PATH settings.
To get a list of existing ORACLE_HOMEs, use the dbcli list-dbhomes command. To create a
new ORACLE_HOME, use the dbcli create-dbhome command.
Skip this section if the source database is not configured with TDE.
3. Copy the ewallet.p12 file from the source database to the directory you created in the
previous step.
4. On the target host, make sure that $ORACLE_HOME/network/admin/sqlnet.ora
contains the following line:
ENCRYPTION_WALLET_LOCATION=(SOURCE=(METHOD=FILE)(METHOD_DATA=
(DIRECTORY=/opt/oracle/dcs/commonstore/wallets/tde/$ORACLE_UNQNAME)))
Add the line if it doesn't exist in the file. (The line might not be there if this is a new
home and no database has been created yet on this host.)
5. Create the autologin wallet from the password-based wallet to allow auto-open of the
wallet during restore and recovery operations.
For version 12c, use the ADMINISTER KEY MANAGEMENT command:
$cat create_autologin_12.sh
#!/bin/sh
if [ $# -lt 2 ]; then
echo "Usage: $0 <db_unique_name> <remote_wallet_location>"
exit 1;
fi
mkdir /opt/oracle/dcs/commonstore/wallets/tde/$1
cp $2/ewallet.p12* /opt/oracle/dcs/commonstore/wallets/tde/$1
rm -f autokey.ora
echo "db_name=$1" > autokey.ora
autokeystoreLog="autologinKeystore_`date +%Y%m%d_%H%M%S_%N`.log"
echo "Enter Keystore Password:"
read -s keystorePassword
echo "Creating AutoLoginKeystore -> "
sqlplus "/as sysdba" <<EOF
spool $autokeystoreLog
set echo on
Set up the static listener for the auxiliary instance for RMAN duplication.
1. Set the following environment variables for RMAN and SQL Plus sessions for the
database:
ORACLE_HOME=<path_of_Oracle_home_where_the database_is_to_be_restored>
ORACLE_SID=<database_name>
ORACLE_UNQNAME=<db_unique_name(in lower case)>
NLS_DATE_FORMAT="mm/dd/yyyy hh24:mi:ss"
3. Create an init.ora file with the minimal required parameters as described in Creating
an Initialization Parameter File and Starting the Auxiliary Instance and use it for the
auxiliary instance.
4. Start the auxiliary instance in nomount mode:
startup nomount
5. Run the following commands to duplicate the database. Note that the example below
uses variables to indicate the values to be specified:
rman target sys/$sourceSysPassword@$sourceNode:$sourceListenerPort/$sourceDb auxiliary
sys/$auxSysPassword@$targetNode:$targetListenerPort/$auxService<<EOF
3. Use the following command to verify that the password file was restored or created for
a new database.
ls -ltr $ORACLE_HOME/dbs/orapw<$ORACLE_SID>
If the file does not exist, create it using the orapwd command.
orapwd file=<$ORACLE_HOME/dbs/orapw<$ORACLE_SID>> password=<sys_password>
4. Use the following command to verify that the restored database is open in read write
mode.
select open_mode from v$database;
Read write mode is required to register the database later. Any PDBs must also be in
read write mode.
5. From oracle home on the migrated database host, use the following command verify the
connection to SYS.
conn sys/<password>@<service_name> as sysdba
This connection is required to register the database later. Fix any connection issues
before continuing.
6. Copy the folder $ORACLE_HOME/sqlpatch from source database to the target database.
This will enable the dbcli register-database command to rollback any conflicting
patches.
Note
7. Use the following SQL*Plus command to make sure the database is using the spfile.
SHOW PARAMETERS SPFILE
The dbcli register-database command registers the migrated database to the dcs-agent so it
can be managed by the dcs-agent stack.
Note
As the root user, use the dbcli register-database command to register the database on
the DB system, for example:
[root@dbsys ~]# dbcli register-database --dbclass OLTP --dbshape odb1 --servicename crmdb.example.com --
syspassword
Password for SYS:
{
"jobId" : "317b430f-ad5f-42ae-bb07-13f053d266e2",
"status" : "Created",
"message" : null,
"reports" : [ ],
"createTimestamp" : "August 08, 2016 05:55:49 AM EDT",
"description" : "Database service registration with db service name: crmdb.example.com",
"updatedTime" : "August 08, 2016 05:55:49 AM EDT"
}
For a 1-node DB system at version 12.1 or higher, the dbcli register-database command
automates the datapatch execution. Before executing the dbcli register-database
command, open all PDBs in read-write mode. If you have already run the dbcli register-
database command and did not open all PDBs, or did not copy the $ORACLE_HOME/sqlpatch
directory from the source database home, manually rerun the datapatch utility to configure
the SQL portion of existing interim patches. This can be done by executing the command
$ORACLE_HOME/OPatch/opatch datapatch.
Tip
For version 11.2 databases, the sqlpatch application is not automated, so any interim patches
(previously known as a "one-off" patches) applied to the source database that are not part of
the installed PSU must be rolled back manually in the target database. After registering the
database, execute the catbundle.sql script and then the postinstall.sql script with the
corresponding PSU patch (or the overlay patch on top of the PSU patch), as described below.
Tip
1. On the DB System, use the dbcli list-dbhomes command to find the PSU patch
number for the version 11.2 database home. In the following sample command output,
the PSU patch number is the second number in the DB Version column:
[root@dbsys ~]# dbcli list-dbhomes
ID Name DB Version
Home Location Status
------------------------------------ ----------------- ------------------------------------- --
--------------------------------------- ----------
59d9bc6f-3880-4d4f-b5a6-c140f16f8c64 OraDB11204_home1 11.2.0.4.160719 (23054319, 23054359)
/u01/app/oracle/product/11.2.0.4/dbhome_1 Configured
(The first patch number, 23054319 in the example above, is for the OCW component in
the database home.)
2. Find the overlay patch, if any, by using the lsinventory command. In the following
example, patch number 24460960 is the overlay patch on top of the 23054359 PSU
patch.
$ $ORACLE_HOME/OPatch/opatch lsinventory
...
Installed Top-level Products (1):
4. Apply the sqlpatch, using the overlay patch number from the previous step, for
example:
SQL> connect / as sysdba
SQL> @$ORACLE_HOME/sqlpatch/24460960/postinstall.sql
exit
If you would like to manage the database backup with the dbcli command line interface, you
can associate a new or existing backup configuration with the migrated database when you
register it or after you register it. A backup configuration defines the backup destination and
recovery window for the database. As the root user, use the following commands to create,
list, and display backup configurations:
l dbcli update-backupconfig
l dbcli list-backupconfigs
l dbcli describe-backupconfig
After the database is migrated and registered on the DB system, use the following checklist to
verify the results of the migration and perform any post-migration customizations.
In this method, you use SQL INSERT statements to load the data into your cloud database.
1. Launch SQL Developer, connect to your on-premises database and create a cart
containing the objects you want to migrate.
2. In SQL Developer, click the Export Cart icon and select “Insert” in the Format menu.
3. In SQL Developer, open a connection to the Oracle Database 12c database in the
Database service and execute the generated script to create the database objects.
4. In SQL Developer, open a connection to the Oracle Database 12c database in the
Database service and run the generated script to create the objects and load the data.
In this method, you use SQL*Loader to load the data into your cloud database.
To migrate selected objects to an Oracle Database 12c database in the Database service
deployment using SQL Developer and SQL*Loader, you perform these tasks:
1. Launch SQL Developer, connect to your on-premises database and create a cart
containing the objects you want to load into your cloud database.
2. In SQL Developer, click the Export Cart icon and select “loader” in the Format menu.
3. In SQL Developer, open a connection to the Oracle Database 12c database on the
Database service and execute the generated script to create the database objects.
4. Use a secure copy utility to transfer the SQL*Loader control files and the SQL*Loader
data files to the Database service compute node.
5. On the Database service compute node, invoke SQL*Loader to load the data using the
SQL*Loader control files and data files for each object.
Unplugging/Plugging a PDB
You can use this method only if the on-premises platform is little endian, and the on-premises
database and the Oracle Cloud Infrastructure Database service database have compatible
database character sets and national character sets.
You can use the unplug/plug method to migrate an Oracle Database 12c PDB to a PDB in an
Oracle Database 12c database on a Database service database deployment.
To migrate an Oracle Database 12c PDB to a PDB in the Oracle Database 12c database on an
Oracle Cloud Infrastructure Database service database deployment using the plug/unplug
method, you perform these tasks:
1. On the on-premises database host, invoke SQL*Plus and close the on-premises PDB.
2. On the on-premises database host, execute the ALTER PLUGGABLE DATABASE UNPLUG
command to generate an XML file containing the list of datafiles that will be plugged in
to the database on the Database service.
3. Use a secure copy utility to transfer the XML file and the datafiles to the
Databaseservice compute node.
4. On the Database service compute node, invoke SQL*Plus and execute the CREATE
PLUGGABLE DATABASE command to plug the database into the CDB.
5. On the Database service compute node, open the new PDB by executing the ALTER
PLUGGABLE DATABASE OPEN command.
For more information, see "Creating a PDB by Plugging an Unplugged PDB into a CDB" in
Oracle Database Administrator's Guide for Release 12.2 or 12.1.
Unplugging/Plugging Non-CDB
You can use this method only if the on-premises platform is little endian, and the on-premises
database and the Oracle Cloud Infrastructure Database database have compatible database
character sets and national character sets.
You can use the unplug/plug method to migrate an Oracle Database 12c non-CDB database to
a PDB in an Oracle Database 12c database on a Database service database deployment. This
method provides a way to consolidate several non-CDB databases into a single Oracle
Database 12c multitenant database on the Database service.
To migrate an Oracle Database 12c non-CDB database to the Oracle Database 12c database on
a Database service deployment using the plug/unplug method, you perform these tasks:
1. On the on-premises database host, invoke SQL*Plus and set the on-premises database
to READ ONLY mode.
2. On the on-premises database host, execute the DBMS_PDB.DESCRIBE procedure to
generate an XML file containing the list of datafiles that will be plugged in on the cloud
database.
3. Use a secure copy utility to transfer the XML file and the datafiles to the Database
service compute node.
4. On the Database service compute node, invoke SQL*Plus and execute the CREATE
PLUGGABLE DATABASE command to plug the database into the CDB.
5. On the Database service compute node, execute the $ORACLE_
HOME/rdbms/admin/noncdb_to_pdb.sql script to delete unnecessary metadata from
the SYSTEM tablespace of the new PDB.
6. On the Database service compute node, open the new PDB by executing the ALTER
PLUGGABLE DATABASE OPEN command.
7. Optionally, on the on-premises database host invoke SQL*Plus and set the on-premises
database back to READ WRITE mode.
For more information, see "Creating a PDB Using a Non-CDB" in Oracle Database
Administrator's Guide for Release 12.2 or 12.1.
Troubleshooting
These topics cover some common issues you might run into and how to address them.
Exadata DB Systems
l Backup Failures on Exadata DB Systems
Tip
This topic includes information to help you determine the cause of a failure and fix the
problem. The section that includes troubleshooting information is organized into several
subsections, based on the error condition. If you already know the cause, you can skip to the
section with the suggested solution. Otherwise, use the procedure in Finding the Problem to
get started.
In the Console, a failed database backup either displays a status of Failed or hangs in the
Backup in Progress or Creating state. If the error message does not contain enough
information to point you to a solution, you can use the database CLI and log files to gather
more data. Then, refer to the applicable section in this topic for a solution.
Note the last job ID listed with a status other than Success.
3. With the job ID you noted from the previous step, use the following command to check
the details of that job:
dbcli describe-job -i <job_ID> -j
Typically, running this command is enough to reveal the root cause of the failure.
4. If you require more information, review the /opt/oracle/dcs/log/dcs-agent.log
file.
You can find the job ID in this file by using the timestamp returned by the job report in
step 2.
5. If the problem details suggest an RMAN issue, review the RMAN logs in the
/opt/oracle/dcs/log/<hostname>/rman/bkup/<db_unique_name>/rman_
backup/<yyyy-mm-dd> directory.
Note
Your Oracle Cloud Infrastructure Database makes use of an agent framework to allow you to
manage your database through the cloud platform. Occasionally you might need to restart the
dcsagent program if it has the status of stop/waiting to resolve a backup failure.
3. Check the status of the agent again to confirm that it has the start/running status:
initctl status initdcsagent
Oracle Clusterware enables servers to communicate with each other so that they can function
as a collective unit. Occasionally you might need to restart the Clusterware program to
resolve a backup failure.
Backing up your database to Oracle Cloud Infrastructure Object Storage requires that the host
can connect to the applicable Swift endpoint. You can test this connectivity by using a Swift
user.
See Object Storage FAQ for the correct region to use. See Understanding Object
Storage Namespaces for information about your Object Storage namespace.
3. If you cannot connect to the object store, refer to Prerequisites for how to configure
object store connectivity.
Host Issues
One or more of the following conditions on the database host can cause backups to fail:
If an interactive command such as oraenv, or any command that might return an error or
warning message, was added to the .bash_profile file for the grid or oracle user, Database
service operations like automatic backups can be interrupted and fail to complete. Check the
.bash_profile file for these commands, and remove them.
Backup operations require space in the /u01 directory on the host file system. Use the df -h
command on the host to check the space available for backups. If the file system has
insufficient space, you can remove old log or trace files to free up space.
Your system might not have the required version of the backup module (opc_installer.jar).
See Unable to use Managed Backups in your DB System for details about this known issue. To
fix the problem, you can follow the procedure in that section or simply update your DB system
and database with the latest bundle patch.
Database Issues
The database must be active and running (ideally on all nodes) while the backup is in
progress.
The system returns a message including the database's instance status. The instance status
must be Open for the backup to succeed. If the database is not running, use the following
command to start it:
srvctl start database -d <db_unique_name> -o open
If the database is mounted but does not have the Open status, use the following commands to
access the SQL*Plus command prompt and set the status to Open:
sqlplus / as sysdba
When you provision a new database, the archiving mode is set to ARCHIVELOG by default. This
is the required archiving mode for backup operations. Check the archiving mode setting for
the database and change it to ARCHIVELOG, if applicable.
If you need to set the archiving mode to ARCHIVELOG, start the database in Mount status (and
not Open status), and use the following command at the SQL*Plus command prompt:
alter database archivelog;
Confirm that the db_recovery_file_dest parameter points to +RECO, and that the log_
archive_dest_1 parameter is set to USE_DB_RECOVERY_FILE_DEST.
For RAC databases, one instance must have the Mount status when enabling archivelog
mode. To enable archivelog mode for a RAC database, perform the following steps:
exit;
7. At the SQL*Plus command prompt, confirm the archiving mode is set to ARCHIVELOG:
select log_mode from v$database;
Backups can fail when the database instance has a stuck archiver process. For example, this
can happen when the flash recovery area (FRA) is full. You can check for this condition using
the srvctl status database -db <db_unique_name> -v command. If the command
returns the following output, you must resolve the stuck archiver process issue before
backups can succeed:
Instance <instance_identifier> is running on node *<node_identifier>. Instance status: Stuck Archiver
After resolving the stuck process, the command should return the following output :
Instance <instance_identifier> is running on node *<node_identifier>. Instance status: Open
If the instance status does not change after you resolve the underlying issue with the device
or resource being full or unavailable, try one of the following workarounds:
l Restart the database using the srvctl command to update the status of the database in
the clusterware
l Upgrade the database to the latest patchset levels
If fixed table statistics are not up to date on the database, backups can fail with errors
referencing temporary tablespace present in the dcs-agent.log file. For example:
select status from v$rman_status where COMMAND_ID=<backup_id>
ERROR at line 1:
ORA-01652: unable to extend temp segment by 128 in tablespace TEMP
exec dbms_stats.gather_fixed_objects_stats();
Editing certain RMAN configuration parameters can lead to backup failures in Oracle Cloud
Infrastructure. To check your RMAN configuration, use the show all command at the RMAN
command line prompt.
See the following list of parameters for details about RMAN the configuration settings that
should not be altered for databases in Oracle Cloud Infrastructure.
The RMAN retention policy configuration can be the source of backup failures. Using the
REDUNDANCY retention policy configuration instead of the RECOVERY WINDOW policy can
lead to backup failures. Be sure to use the RECOVERY WINDOW OF 30 DAYS configuration.
2. Find the BackupConfigId value for the database using the following command:
dbcli describe-database -i <database_id>
RMAN backups fail when an object store wallet file is lost. The wallet file is necessary to
enable connectivity to the object store.
To confirm that the object store wallet file exists and has the correct
permissions
1. Find the database ID using the following command:
dbcli list-databases
2. Find the BackupConfigId value for the database using the following command:
3. Find the BackupLocation value for the database using the following command:
dbcli describe-backupconfig <backup_config_id>
4. Find the file path of the backup config parameter file (opc_<backup_location_value>_
BC.ora) using the following command:
locate opc_<backup_location_value>_BC.ora
For example:
[root@orcl 13aef284-9d6b-4eb6-8751-2988aexample]# locate op
/opt/oracle/dcs/commonstore/objectstore/opc_pfile/13aef284-
2988a9example/opc_b9naijWMAXzi9example_BC.ora
5. Find the file path to the wallet file in the backup config parameter file by inspecting the
value stored in the OPC_WALLET parameter. To do this, navigate to the directory
containing the backup config parameter file and use the following cat command:
cat <backup_config_parameter_file>
For example:
[root@orcl 13aef284-9d6b-4eb6-8751-2988aexample]# cat opc_b
OPC_HOST=https://swiftobjectstorage.us-ashburn-1.oracleclou
OPC_WALLET='LOCATION=file:/opt/oracle/dcs/commonstore/objec
4eb6-8751-2988aexample CREDENTIAL_ALIAS=alias_opc'
OPC_CONTAINER=b9naijWMAXzi9example
6. Confirm that the cwallet.sso file exists in the directory specified in the OPC_WALLET
parameter, and confirm that the file has the correct permissions. The file permissions
should have the octal value of "600" (-rw-------). Use the following command:
ls -ltr /opt/oracle/dcs/commonstore/objectstore/wallets/<backup_config_id>
For example:
[root@orcl 13aef284-9d6b-4eb6-8751-2988aexample]# ls -ltr
/opt/oracle/dcs/commonstore/objectstore/wallets/13aef284-9d6b-4eb6-8751-2988aexample
total 4
Important
ENCRYPTION_WALLET_LOCATION=(SOURCE=(METHOD=FILE)(METHOD_DATA=
(DIRECTORY=/opt/oracle/dcs/commonstore/wallets/tde/$ORACLE_UNQNAME)))
Database backups fail if the TDE wallet is not in the proper state. The following scenarios can
cause this problem:
The ORACLE_UNQNAME environment variable was not set when the database
was started using SQL*Plus
If the database was started using SQL*Plus, and the ORACLE_UNQNAME environment variable
was not set, the wallet is not opened correctly.
To fix the problem, start the database using the srvctl utility:
srvctl start database -d <db_unique_name>
To check the master encryption key status and create a master key, do the following:
1. Review the the STATUS column in the v$encryption_wallet view, as shown in the
following example:
SQL> alter session set container=pdb2;
Session altered.
WRL_TYPE WRL_PARAMETER
WALLET_TYPE
--------------- -------------------------------------------
---------
FILE /opt/oracle/dcs/commonstore/wallets/tde/example_iad
AUTOLOGIN
2. Confirm that the PDB is in READ WRITE open mode and is not restricted, as shown in the
following example:
SQL> show pdbs
The PDB cannot be open in restricted mode (the RESTRICTED column must show NO). If
the PDB is currently in restricted mode, review the information in the PDB_PLUG_IN_
VIOLATIONS view and resolve the issue before continuing. For more information on the
PDB_PLUG_IN_VIOLATIONS view and the restricted status, review the documentation
on pluggable database for your Oracle database version.
3. Run the following DBCLI commands to change the status to OPEN:
$ sudo su –
# dbcli list-database
# dbcli update-tdekey -i <database_ID> -n <PDB_name> -p
The update-tdekey command shown will prompt you for the admin password.
4. Confirm that the status of the wallet has changed from OPEN_NO_MASTER_KEY to OPEN
by querying the v$encryption_wallet view as shown in step 1.
Several configuration parameters related to the TDE wallet can cause backups to fail.
For example:
[oracle@orcl tde]$ srvctl getenv database -d orclbkp_iadxyz
orclbkp_iadxyz:
ORACLE_UNQNAME=orclbkp_iadxyz
TZ=UTC
l Check your sqlnet.ora settings to confirm that the file has an ENCRYPTION_WALLET_
LOCATION parameter with the correct DIRECTORY value. Use the following command:
cat $ORACLE_HOME/network/admin/sqlnet.ora
For example:
[oracle@orcl tde]$ cat $ORACLE_HOME/network/admin/sqlnet.or
ENCRYPTION_WALLET_LOCATION=(SOURCE=(METHOD=FILE)(METHOD_DATA=
(DIRECTORY=/opt/oracle/dcs/commonstore/wallets/tde/$ORACLE_UNQNAME)))
l Confirm that the wallet status is open and the wallet type is auto login by checking the
v$encryption_wallet view. For example:
SQL> select status, wrl_parameter,wallet_type from v$encryp
STATUS WRL_PARAMETER
WALLET_TYPE
------------------------------ ----------------------------
---------------
OPEN /opt/oracle/dcs/commonstore/wallets/
AUTOLOGIN
For pluggable databases (PDBs), be sure that you switch to the appropriate container
before querying v$encryption_wallet view. For example:
Session altered.
WRL_TYPE WRL_PARAMETER
---------- ------------------------------------------------
---------
FILE /opt/oracle/dcs/commonstore/wallets/tde/tiger_iad3c8/
The TDE wallet file (ewallet.p12) can cause backups to fail if it is missing, or if it has
incompatible file system permissions or ownership. Check the file as shown in the following
example:
[oracle@orcl tde]$ ls -ltr /opt/oracle/dcs/commonstore/wallets/tde/$ORACLE_UNQNAME/ewallet.p12
The TDE wallet file should have file permissions with the octal value "700" (-rwx------), and
the owner of this file should be a part of the oinstall operating system group.
The auto login wallet file (cwallet.sso) can cause backups to fail if it is missing, or if it has
incompatible file system permissions or ownership. Check the file as shown in the following
example:
[oracle@orcl tde]$ ls -ltr /opt/oracle/dcs/commonstore/wallets/tde/$ORACLE_UNQNAME/cwallet.sso
The auto login wallet file should have file permissions with the octal value "700" (-rwx-----
-), and the owner of this file should be a part of the oinstall operating system group.
Mount users:
Type: ACFS
NAME=ora.data.commonstore.acfs
TYPE=ora.acfs.type
LAST_SERVER=orcl
STATE=OFFLINE
TARGET=OFFLINE
...
...
total 0
If the STATE_DETAILS value is unmounted, mount the file system as shown in the following
example:
[root@orcl ~]# srvctl start filesystem -volume commonstore -diskgroup data
Confirm that the change was successful as shown in the following example:
[root@orcl ~]# crsctl stat resource ora.data.commonstore.acfs -v
NAME=ora.data.commonstore.acfs
TYPE=ora.acfs.type
LAST_SERVER=orcl
STATE=ONLINE on orcl
TARGET=ONLINE
CARDINALITY_ID=ONLINE
...
STATE_DETAILS=mounted on /opt/oracle/dcs/commonstore
List the contents of the commonstore directory to confirm that it is mounted, as shown in the
following example:
[root@orcl ~]# ls -ltr /opt/oracle/dcs/commonstore
total 220
Database backups fail if the database is not registered with the dcs-agent. This scenario can
occur if you manually migrate the database to Oracle Cloud Infrastructure and do not run the
dbcli register-database command.
To check whether the database is properly registered, review the information returned by
running the srvctl config database command and the dbcli list-databases command.
If either command does not return a record of the database, contact Oracle Support Services.
For instructions on how to register the database, refer to the following topics:
Getting Help
If you were unable to resolve the problem using the information in this topic, follow the
procedures below to collect relevant database and diagnostic information. After you have
collected this information, contact Oracle Support.
dbcli describe-component
The <job_ID> in the second command should be the ID of the latest failed job reported
from the first command.
3. Run the diagnostics collector script to create a zip file with the diagnostic information
for Oracle Support Services.
diagcollector.py
sudo /opt/oracle/dcs/bin/diagcollector.py
3. The system returns a message indicating that agent logs are available in a zip file at a
specified directory. For example:
[opc@prodpr ~]$ sudo /opt/oracle/dcs/bin/diagcollector.py
/tmp/dcsdiag/diagLogs-1234567890.zip
STATUS WRL_PARAMETER
--------------- -------------------------------------------
OPEN /opt/oracle/dcs/commonstore/wallets/tde/example_iad
3. Record the output of the output of the ls -ltr <wrl_parameter> command. For
example:
[oracle@patchtst ~]$ ls -ltr /opt/oracle/dcs/commonstore/wa
total 28
For example:
[root@patchtst ~]# dbcli create-rmanbackupreport -i 57fvwxyz-9dc4-45d3-876b-5f850example -w detailed -rn
bkpreport1
Locate the report file using the dbcli describe-rmanbackupreport -in <report_name>
command. The location of the report is given in output. For example:
[root@patchtst ~]# dbcli describe-rmanbackupreport -in bkpreport1
----------------------------------------------------------------
ID: b55vwxyz-c49f-4af3-a956-acccdexample
This topic includes information to help you determine the cause of the failure and fix the
problem. The information is organized into several sections, based on the error condition. If
you already know the cause, you can skip to the section with the suggested solution.
Otherwise, use the procedure in Determining the Problem to get started.
In the Console, you can identify a failed patching operation by viewing the patch history of a
DB system or an individual database. A patch that was not successfully applied displays a
status of Failed and includes a brief description of the error that caused the failure. If the
error message does not contain enough information to point you to a solution, you can use the
database CLI and log files to gather more data. Then, refer to the applicable section in this
topic for a solution.
Note the last job ID listed with a status other than Success.
3. With the job ID you noted from the previous step, use the following command to check
the details of that job:
dbcli describe-job -i <job_ID> -j
Typically, running this command is enough to reveal the root cause of the failure.
4. If you require more information, review the /opt/oracle/dcs/log/dcs-agent.log
file.
You can find the job ID in this file by using the timestamp returned by the job report in
step 2.
Note
Your Oracle Cloud Infrastructure Database makes use of an agent framework to allow you to
manage your database through the cloud platform.
Occasionally you might need to restart the dcsagent program if it has the status of
stop/waiting to resolve a patching failure.
3. Check the status of the agent again to confirm that it has the start/running status:
initctl status initdcsagent
Patching can also fail if your agent needs to be updated. The system gives the following error
message for this failure:
Current DcsAgent version is less than or equal to minimum required version.
To resolve this issue, perform the steps in To have Oracle Support update the Oracle Cloud
Infrastructure Database service agent.
If these programs are not running, use the following commands to restart them:
initctl start initdcsagent
2. Follow the instructions in Obtaining Further Assistance to collect your DCS agent log
files.
3. Contact Oracle Support for assistance with updating the agent.
Oracle Cloud Infrastructure DB system and database patches are stored in Oracle Cloud
Infrastructure Object Storage. Therefore, successful patching operations require connectivity
between the DB system host and the Object Storage location from which the patches are
downloaded.
componentType availableVersion
--------------- --------------------
gi 12.2.0.1.180417
gi 12.1.0.2.180417
gi 18.2.0.0.180417
db 11.2.0.4.180417
db 12.2.0.1.180417
db 12.1.0.2.180417
db 18.2.0.0.180417
oak 12.1.2.11.3
oak 12.2.1.1.0
2. If you cannot connect to the object store, refer to Prerequisites for how to configure
object store connectivity.
One or more of the following conditions on the database host can cause patching operations to
fail:
All nodes of the database must be active and running while a patching operation is in
progress, whether you are patching the DB system or the database home. Use the Console to
check that the status of each node is AVAILABLE, and start the node, if needed.
Patching operations require a minimum of 15 GB of free space in the /u01 directory on the
host file system. Use the df -h command on the host to check the available space. If the file
system has insufficient space, you can remove old log or trace files to free up space.
Oracle Clusterware enables servers to communicate with each other so that they can function
as a collective unit. The cluster software program must be up and running on the DB system
for patching operations to complete. Occasionally you might need to restart the Oracle
Clusterware to resolve a patching failure.
Example output:
[grid@<host> ~]$ crsctl check crs
CRS-4638: Oracle High Availability Services is online
CRS-4537: Cluster Ready Services is online
CRS-4529: Cluster Synchronization Services is online
CRS-4533: Event Manager is online
For more detailed status information, you can run crsctl stat res -t.
2. If Oracle Clusterware is not online, try to restart the program:
crsctl start crs
This problem occurs when you try to patch a database before you patch the DB system of that
database. The error description indicates that the Oracle Grid Infrastructure must be updated
first. To resolve this issue, patch the DB system to latest available version. After you patch
the DB system, you can retry the database patching operation.
To get the current and latest-available GI versions for the DB system, use the following
command:
dbcli describe-component
Database Issues
The database must be active and running for all of the patching tasks to complete. Otherwise,
you must run the datapatch task manually.
The system returns a message including the database instance status. The instance status
must be Open for the patching operation to succeed.
If the database is not running, use the following command to start it:
srvctl start database -d <db_unique_name> -o open
If the database is mounted but does not have the Open status, use the following commands to
access the SQL*Plus command prompt and set the status to Open:
sqlplus / as sysdba
If you were unable to resolve the problem using the information in this topic, follow the
procedures below to collect relevant database and diagnostic information. After you have
collected this information, contact Oracle Support.
The <job_ID> in the second command should be the ID of the latest failed job reported
from the first command.
3. Run the diagnostics collector script to create a zip file with the diagnostic information
for Oracle Support Services.
diagcollector.py
3. The system returns a message indicating that agent logs are available in a zip file at a
specified directory. For example:
/tmp/dcsdiag/diagLogs-1234567890.zip
Oracle Database
$ORACLE_HOME/cfgtoollogs/
The information that follows is organized by the error condition. If you already know the
cause, you can skip to the section with the suggested solution. Otherwise, use the procedure
in Determining the Problem to get started.
In the Console, a failed database backup either displays a status of Failedor hangs in the
Backup in Progress or Creating state. If the error message does not contain enough
information to point you to a solution, you can gather more information by using the dbaascli
tool and by viewing the log files. Then, refer to the applicable section in this topic for a
solution.
Note
Your Oracle Cloud Infrastructure Database makes use of an agent framework to allow you to
manage your database through the cloud platform. Occasionally you might need to restart the
dcsagent program if it has the status of stop/waiting to resolve a backup failure. View the
/opt/oracle/dcs/log/dcs-agent.log file to identify issues with the agent.
3. Check the status of the agent again to confirm that it has the start/running status:
systemctl status dbcsagent.service
Backing up your database to Oracle Cloud Infrastructure Object Storage requires that the host
can connect to the applicable Swift endpoint. Though Oracle controls the actual Swift user
credentials for the storage bucket for managed backups, verifying general connectivity to
Object Storage in your region is a good indicator that object store connectivity is not the
issue. You can test this connectivity by using another Swift user.
See Object Storage FAQ for the correct region to use. See Understanding Object
Storage Namespaces for information about your Object Storage namespace.
3. If you cannot connect to the object store, refer to Prerequisites for how to configure
object store connectivity.
Host Issues
One or more of the following conditions on the database host can cause backups to fail:
If an interactive command such as oraenv, or any command that might return an error or
warning message, was added to the .bash_profile file for the grid or oracle user, Database
service operations like automatic backups can be interrupted and fail to complete. Check the
.bash_profile file for these commands, and remove them.
Backup operations require space in the /u01 directory on the host file system. Use the df -h
command on the host to check the space available for backups. If the file system has
insufficient space, you can remove old log or trace files to free up space.
Your system might not have the required version of the backup module (opc_installer.jar).
See Unable to use Managed Backups in your DB System for details about this known issue. To
fix the problem, you can follow the procedure in that section or simply update your DB system
and database with the latest bundle patch.
Database Issues
The database must be active and running (ideally on all nodes) while the backup is in
progress.
The system returns a message including the database's instance status. The instance status
must be Open for the backup to succeed. If the database is not running, use the following
command to start it:
srvctl start database -d <db_unique_name> -o open
If the database is mounted but does not have the Open status, use the following commands to
access the SQL*Plus command prompt and set the status to Open:
sqlplus / as sysdba
When you provision a new database, the archiving mode is set to ARCHIVELOG by default. This
is the required archiving mode for backup operations. Check the archiving mode setting for
the database and change it to ARCHIVELOG, if applicable.
If you need to set the archiving mode to ARCHIVELOG, start the database in Mount status (and
not Open status), and use the following command at the SQL*Plus command prompt:
alter database archivelog;
Confirm that the db_recovery_file_dest parameter points to +RECO, and that the log_
archive_dest_1 parameter is set to USE_DB_RECOVERY_FILE_DEST.
For RAC databases, one instance must have the Mount status when enabling archivelog
mode. To enable archivelog mode for a RAC database, perform the following steps:
exit;
7. At the SQL*Plus command prompt, confirm the archiving mode is set to ARCHIVELOG:
select log_mode from v$database;
Backups can fail when the database instance has a stuck archiver process. For example, this
can happen when the flash recovery area (FRA) is full. You can check for this condition using
the srvctl status database -db <db_unique_name> -v command. If the command
returns the following output, you must resolve the stuck archiver process issue before
backups can succeed:
Instance <instance_identifier> is running on node *<node_identifier>. Instance status: Stuck Archiver
After resolving the stuck process, the command should return the following output:
Instance <instance_identifier> is running on node *<node_identifier>. Instance status: Open
If the instance status does not change after you resolve the underlying issue with the device
or resource being full or unavailable, try restarting the database using the srvctl command
to update the status of the database in the clusterware.
Editing certain RMAN configuration parameters can lead to backup failures in Oracle Cloud
Infrastructure. To check your RMAN configuration, use the show all command at the RMAN
command line prompt.
See the following list of parameters for details about RMAN the configuration settings that
should not be altered for databases in Oracle Cloud Infrastructure.
RMAN backups fail when an object store wallet file is lost. The wallet file is necessary to
enable connectivity to the object store.
To confirm that the object store wallet file exists and has the correct
permissions
1. Get the name of the database with the backup failure:
SQL> show parameter db_name
2. Determine the file path of the backup config parameter file that contains the RMAN
wallet information:
locate opc_<database_name>.ora
3. Find the file path to the wallet file in the backup config parameter file by inspecting the
value stored in the OPC_WALLET parameter. To do this, navigate to the directory
containing the backup config parameter file and use the following cat command:
cat opc<database_name>.ora
For example:
[root@khdyygw-mpjxb1Example ]# cd /var/opt/oracle/dbaas_acfs/testdb30/opc/
[root@khdyygw-mpjxb1Example ]# ls -altr *.ora
opctestdb30.ora
[root@khdyygw-mpjxb1Example ]# cat opctestdb30.ora
OPC_HOST=https://swiftobjectstorage.us-phoenix-1.oraclecloud.com/v1/dbbackupphx
OPC_WALLET='LOCATION=file:/var/opt/oracle/dbaas_acfs/testdb30/opc/opc_wallet CREDENTIAL_
ALIAS=alias_opc'
OPC_CONTAINER=bUG3TFsSi8QzjWfuTxqqExample
_OPC_DEFERRED_DELETE=false
4. Confirm that the cwallet.sso file exists in the directory specified in the OPC_WALLET
parameter, and confirm that the file has the correct permissions. The file permissions
should have the octal value of "600" (-rw-------). Use the following command:
ls -ltr /var/opt/oracle/dbaas_acfs/<database_name>/opc/opc_wallet
For example:
[root@khdyygw-mpjxb1Example]# ls -altr /var/opt/oracle/dbaas_acfs/testdb30/opc/opc_wallet
-rw------- 1 oracle oinstall 0 Oct 29 01:59 cwallet.sso.lck
-rw------- 1 oracle oinstall 111231 Oct 29 01:59 cwallet.sso
Database backups fail if the TDE wallet is not in the proper state. The following scenarios can
cause this problem:
The ORACLE_UNQNAME environment variable was not set when the database
was started using SQL*Plus
If the database was started using SQL*Plus, and the ORACLE_UNQNAME environment variable
was not set, the wallet is not opened correctly.
To fix the problem, start the database using the srvctl utility:
srvctl start database -d <db_unique_name>
To check the master encryption key status and create a master key, do the following:
1. Review the the STATUS column in the v$encryption_wallet view, as shown in the
following example:
SQL> alter session set container=pdb2;
Session altered.
2. Confirm that the PDB is in READ WRITE open mode and is not restricted, as shown in the
following example:
The PDB cannot be open in restricted mode (the RESTRICTED column must show NO). If
the PDB is currently in restricted mode, review the information in the PDB_PLUG_IN_
VIOLATIONS view and resolve the issue before continuing. For more information on the
PDB_PLUG_IN_VIOLATIONS view and the restricted status, review the documentation
on pluggable database for your Oracle database version.
3. Create and activate a master encryption key for the PDB:
l Set the container to the PDB:
SQL> ALTER SESSION SET CONTAINER = pdb;
l Create and activate a master encryption key in the PDB by executing the following
command:
SQL> ADMINISTER KEY MANAGEMENT SET KEY USING TAG '<tag>' FORCE KEYSTORE IDENTIFIED BY
<keystore-password> WITH BACKUP USING '<backup_identifier>';
Configuration parameters related to the TDE wallet can cause backups to fail.
For pluggable databases (PDBs), ensure that you switch to the appropriate container before
querying v$encryption_wallet view. For example:
[oracle@paulo ~]$ sqlplus / as sysdba
Session altered.
The TDE wallet file (ewallet.p12) can cause backups to fail if it is missing, or if it has
incompatible file system permissions or ownership. Check the file as shown in the following
example:
The TDE wallet file should have file permissions with the octal value "600" (-rw-------), and
the owner of this file should be a part of the oinstall operating system group.
The auto login wallet file (cwallet.sso) can cause backups to fail if it is missing, or if it has
incompatible file system permissions or ownership. Check the file as shown in the following
example:
[root@khdyygw-mpjxb1example /]# ls -altr /var/opt/oracle/dbaas_acfs/<database_name>/tde_
wallet/cwallet.sso
total 76
-rw------ 1 oracle oinstall 5512 Oct 1 20:18 cwallet.sso
The auto login wallet file should have file permissions with the octal value "600" (-rw------
-), and the owner of this file should be a part of the oinstall operating system group.
If you were unable to resolve the problem using the information in this topic, follow the
instructions in Diagnostic Data Collection For Oracle Database Cloud Service Instances (OCI-
C) (Doc ID 2219712.1) to collect relevant database and diagnostic information. After you have
collected this information, contact Oracle Support.
Oracle Cloud Infrastructure's Autonomous Data Warehouse APIs were deprecated on Feb. 15,
2019.
Important! Support for these Autonomous Data Warehouse APIs will end on Jul. 1, 2020.
Oracle recommends that you migrate your database workloads to the replacement APIs as
soon as possible.
CreateAutonomousDataWarehouse CreateAutonomousDatabase
ListAutonomousDataWarehouses ListAutonomousDatabases
GetAutonomousDataWarehouse GetAutonomousDatabase
StartAutonomousDataWarehouse StartAutonomousDatabase
StopAutonomousDataWarehouse StopAutonomousDatabase
UpdateAutonomousDataWarehouse UpdateAutonomousDatabase
GenerateAutonomousDataWarehouseWallet GenerateAutonomousDatabaseWallet
RestoreAutonomousDataWarehouse RestoreAutonomousDatabase
DeleteAutonomousDataWarehouse DeleteAutonomousDatabase
CreateAutonomousDataWarehouseBackup CreateAutonomousDatabaseBackup
ListAutonomousDataWarehouseBackups ListAutonomousDatabaseBackups
GetAutonomousDataWarehouseBackup GetAutonomousDatabaseBackup
DOMAIN
Domain names identify a specific location or group of locations on the Internet as a whole.
A common definition of "domain" is the complete portion of the DNS tree that has been
delegated to a user's control. For example, example.com or oracle.com.
ZONE
A zone is a portion of the DNS namespace. A Start of Authority record (SOA) defines a
zone. A zone contains all labels underneath itself in the tree, unless otherwise specified.
LABEL
Labels are prepended to the zone name, separated by a period, to form the name of a
subdomain. For example, the "www" section of www.example.com or the "docs" and "us-
ashburn-1" sections of docs.us-ashburn-1.oraclecloud.com are labels. Records are
associated with these domains.
CHILD ZONE
Child zones are independent subdomains with their own Start of Authority and Name
Server (NS) records. The parent zone of a child zone must contain NS records that refer
DNS queries to the name servers responsible for the child zone. Each subsequent child
zone creates another link in the delegation chain.
RESOURCE RECORDS
A record contains specific domain information for a zone. Each record type contains
information called record data (RDATA). For example, the RDATA of an A or AAAA record
contains an IP address for a domain name, while MX records contain information about
the mail server for a domain. OCI normalizes all RDATA into the most machine readable
format. The returned presentation of your RDATA may differ from its initial input. For
more information about RDATA, please see Supported DNS Resource Record Types.
DELEGATION
To access the Console, you must use a supported browser. You can use the Console link at the
top of this page to go to the sign-in page. Enter your tenancy, user name, and your password.
An administrator in your organization needs to set up groups, compartments, and policies that
control which users can access which services, which resources, and the type of access. For
example, the policies control who can create new users, create and manage the cloud
network, launch instances, create buckets, download objects, etc. For more information, see
Getting Started with Policies. For specific details about writing policies for each of the
different services, see Policy Reference.
If you’re a regular user (not an administrator) who needs to use the Oracle Cloud
Infrastructure resources that your company owns, contact your administrator to set up a user
ID for you. The administrator can confirm which compartment or compartments you should be
using.
If you're new to policies, see Getting Started with Policies and Common Policies. For more
details about policies for DNS, see Details for the DNS Service.
What is DNS?
The Domain Name System (DNS) translates human-readable domain names to machine-
readable IP addresses. A DNS nameserver stores the DNS records for a zone, and responds
with answers to queries against its database. When you type a domain name into your
browser, your operating system queries several DNS nameservers until it finds the
authoritative nameserver for that domain. The authoritative nameserver then responds with
an IP address or other requested record data. The answer is then relayed back to your
browser and the DNS record is resolved to the web page.
Creating a Zone
In this step, you will create a zone. A zone holds the trusted DNS records that will reside on
Oracle Cloud Infrastructure’s nameservers.
To add a zone
1. Open the navigation menu. Under Core Infrastructure, go to Networking and click
DNS Zone Management.
2. Click Create Zone.
3. In the Create Zone dialog box, choose one of the following methods:
l Manual - Enter the following:
o Zone Name: Enter the name of a zone you want to create. Avoid entering
confidential information.
o Zone Type: If you want to control the zone contents directly within Oracle
Cloud Infrastructure, select Primary. If you want Oracle Cloud
Infrastructure to pull zone contents from an external server, select
Secondary and enter your Zone Master Server IP address.
l Import - Drag and drop, select, or paste a valid zone file into the Import Zone
File window. The zone is imported as a primary zone. For information about
formatting a zone file, see Formatting a Zone File.
4. Click Submit.
The system creates and publishes the zone, complete with the necessary SOA and NS records.
For more information on adding a record to your zone, see To add a zone record.
In this step, you will delegate your domain with your registrar. Delegating your domain with
your domain's registrar makes your Oracle Cloud Infrastructure hosted zone accessible
through the internet.
To delegate a zone
1. Open the navigation menu. Under Core Infrastructure, go to Networking and click
DNS Zone Management.
2. Click the Zone Name for the zone you want to delegate. Zone details and a list of
records appear.
3. Use the Type sort filter to locate the NS records for your zone.
4. Note the name servers in the RDATA field within each NS record.
5. You can use the noted name servers to change your domain's DNS delegation. Refer to
your registrar's documentation for instructions.
Note
Tip
There are many record types you can add to your zone,
depending on your goals for the zone and its DNS
management.
1. Open the navigation menu. Under Core Infrastructure, go to Networking and click
DNS Zone Management.
2. Click the Zone Name in which you want to add a record. Zone details and a list of
records appear.
Tip
You can use the Zone Name sort filter to list to sort
zone names alphanumerically in ascending or
descending order.
For a complete list of records supported by Oracle Cloud Infrastructure DNS, see Supported
Resource Records.
A
An address record used to point a hostname to an IPv4 address. For more information
about A records, see RFC 1035.
AAAA
An address record used point a hostname at an IPv6 address. For more information about
AAAA records, see RFC 3596.
CNAME
A Canonical Name record identifies the canonical name for a domain. For more
information about CNAME records, see RFC 1035.
Note
MX
A Mail Exchanger record defines the mail server accepting mail for a domain. MX records
must point to a hostname. MX records must not point to a CNAME or IP address. For more
information about MX records, see RFC 1035.
TXT
A Text record holds descriptive, human readable text, and can also include non-human
readable content for specific uses. It is commonly used for SPF records and DKIM records
that require non-human readable text items. For more information about TXT records, see
RFC 1035.
Using the Domain Information Groper (dig) command line tool, you can test against the
delegation where your domain is hosted, and you will immediately see whether the change
took place without accounting for the cache or TTL (Time to Live) that you have configured.
For more information on using dig to test your DNS, see Testing DNS Using BIND'S dig Tool.
To add a zone
1. Open the navigation menu. Under Core Infrastructure, go to Networking and click
DNS Zone Management.
2. Click Create Zone.
3. In the Create Zone dialog box, choose one of the following methods:
l Manual - Enter the following:
o Zone Name: Enter the name of a zone you want to create. Avoid entering
confidential information.
o Zone Type:
n Primary - Select this option if you want to control the zone contents
directly within Oracle Cloud Infrastructure.
n Secondary - Select this option if you want Oracle Cloud
Infrastructure to pull zone contents from an external server. Enter
your Master Server IP address. Optionally, you can select an
existing TSIG key in a specified compartment that is associated with
the master server. For more information, see Managing TSIG Keys.
l Import - Drag and drop, select, or paste a valid zone file into the Import Zone
File window. The zone is imported as a primary zone. For information about
formatting a zone file or how to amend a zone file exported from GoDaddy.com,
see Formatting a Zone File.
4. Click Create.
The system creates and publishes the zone, complete with the necessary SOA and NS records.
For more information on adding a record to your zone, see To add a zone record.
Tip
You can use the Zone Type sort filter to sort zone
type alphanumerically in ascending or descending
order.
Tip
To delete a zone
Warning
1. Open the navigation menu. Under Core Infrastructure, go to Networking and click
DNS Zone Management.
2. Select the checkbox for the zone you want to delete.
3. Click Delete. The zone is staged for deletion.
4. Click Publish Changes to delete the zone.
5. In the confirmation dialog box, click Publish Changes.
Tip
There are many record types you can add to your zone,
1. Open the navigation menu. Under Core Infrastructure, go to Networking and click
DNS Zone Management.
2. Click the Zone Name in which you want to add a record. Zone details and a list of
records appear.
Tip
You can use the Zone Name sort filter to list to sort
zone names alphanumerically in ascending or
descending order.
Note
Protected Records
1. Open the navigation menu. Under Core Infrastructure, go to Networking and click
DNS Zone Management.
2. Click the Zone Name in which you want to update a record. Zone details and a list of
records appear.
Tip
You can use the Zone Name sort filter to sort zone
names alphanumerically in ascending or descending
order.
3. To help find a record, you can use the following filter options:
l Enter the name of the record's domain in the Search field.
l To find unpublished records, select the Staged check box.
l To find published records, select the Unstaged check box.
l Use the Domain, TTL, or Type sort filter to sort records.
4. Select the checkbox for the record you want to update, and select Edit from the
Actions drop-down menu.
5. In the Edit Record dialog box, make the needed changes, and then click Submit.
You can revert records to their current published state before you publish changes. Once a
record has been published, it cannot be reverted. Select the checkbox for the record you want
to revert, and then select Revert from the Actions drop-down menu.
Tip
You can use the Zone Name sort filter to sort zone
names alphanumerically in ascending or descending
order.
3. Select the checkbox for the record you want to delete, and then select Delete from the
Actions drop-down menu.
4. Click Publish Changes.
5. In the confirmation dialog box, click Publish Changes.
To delegate a zone
To make your Oracle Cloud Infrastructure hosted zone accessible through the internet, you
must delegate your domain with your domain's registrar.
1. Open the navigation menu. Under Core Infrastructure, go to Networking and click
DNS Zone Management.
2. Click the Zone Name for the zone you want to delegate. Zone details and a list of
records appear.
3. Use the Type sort filter to locate the NS records for your zone.
4. Note the name servers in the RDATA field within each NS record.
5. You can use the noted name servers to change your domain's DNS delegation. Refer to
your registrar's documentation for instructions.
4. Click Publish.
5. In the confirmation dialog box, click Publish Changes. Changes cannot be made to this
zone while it is updating. Updating a secondary zone locks it for a short time while our
servers sync with your external master servers.
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.
l GetZone
l ListZones
l CreateZone
l UpdateZone
l DeleteZone
l PatchZoneRecords (add or delete records)
l UpdateZoneRecords
l Verifying a relationship between the owner of a domain name and the owner of the
server (IP address).
l Writing a human readable hostname to the log files for system monitoring tools.
l Determining which hostname is affected when maintenance is performed on an IP
address.
Before getting started with setting up reverse DNS within your Oracle Cloud Infrastructure
account, contact your IP provider and confirm that they allow delegation of your reverse DNS
zone. If they do not allow delegation, typically they can host your pointer record (PTR) for you
and no reverse DNS configurations are required within your Oracle Cloud Infrastructure
account. If they do allow delegation, confirm the exact syntax of the reverse DNS hostname
with them, as some providers use slashes and some use dashes. Additionally, if you are
delegating a reverse DNS zone, confirm that this zone matches exactly what you configure in
your Oracle Cloud Infrastructure account as this is necessary in order for delegation to work
properly.
After you create and publish your reverse DNS zone and PTR records, you can update your
reverse DNS zone delegation with your IP provider. Delegation changes are not required with
your domain registrar with a reverse DNS zone.
Setting up a reverse DNS zone is different for the two types of IP address blocks. Use the
following procedures to set up a reverse DNS zone for your IP address block type.
S ETTING UP REVERSE DNS FOR CLASSLESS ADDRESS BLOCK (PARTIAL RANGE OF IP ADDRESSES)
To find your reverse DNS zone name using classless address block
1. Make a note of your network IP address. For example, 192.168.15.224/27.
2. Remove the netmask portion of the address. This is the number after the slash (/). For
example, remove the '27' after your IP address, 192.168.15.224/27.
3. Reverse the order of the remaining octets. For example, 224.15.168.192.
Note
5. Add the netmask back into the address. For example, 224-27.15.168.192.in-
addr.arpa.
l Import - Drag and drop, select, or paste a valid zone file into the Import Zone
File window. The zone is imported as a primary zone. For information about
formatting a zone file or how to amend a zone file exported from GoDaddy.com,
see Formatting a Zone File.
4. Click Submit.
The system creates and publishes the zone, complete with the necessary SOA and NS records.
1. Open the navigation menu. Under Core Infrastructure, go to Networking and click
DNS Zone Management.
2. Click the Zone Name in which you want to add the PTR record. Zone details and a list of
records appear.
Tip
You can use the Zone Name sort filter to list to sort
zone names alphanumerically in ascending or
descending order.
1. Make a note of the IP address and your desired CNAME for each host in your new
reverse DNS zone.
2. Contact your ISP and request that they append a CNAME record for each host in your
Oracle Cloud Infrastructure DNS zone to your account with them.
3. Test the reverse DNS path by running the following command:
dig -x <insert any regular forward-formatted IP address from the zone> +trace
See Testing DNS Using BIND'S dig Tool for more information.
The returned information should show that your reverse domain is now being resolved.
1. Open the navigation menu. Under Core Infrastructure, go to Networking and click
DNS Zone Management.
2. Click the Zone Name for the zone you want to delegate. Zone details and a list of
records appear.
3. Use the Type sort filter to locate the NS records for your zone.
4. Note the name servers in the RDATA field within each NS record.
You can use the noted name servers to change your domain's DNS delegation. Refer to your
registrar's documentation for instructions.
To find your reverse DNS zone name using full address block
1. Make a note of your network IP address. For example, 192.168.15.0.
2. Remove the netmask portion of the address (the last number in the set of 4). For
example, 192.168.15.
3. Reverse the order of the remaining three octets. For example, 15.168.192.
4. Append ‘in-addr.arpa’ to the end. For example, 15.168.192.in-addr.arpa
The system creates and publishes the zone, complete with the necessary SOA and NS records.
1. Open the navigation menu. Under Core Infrastructure, go to Networking and click
DNS Zone Management.
2. Click the Zone Name in which you want to add the PTR record. Zone details and a list of
records appear.
Tip
You can use the Zone Name sort filter to list to sort
zone names alphanumerically in ascending or
descending order.
1. Open the navigation menu. Under Core Infrastructure, go to Networking and click
DNS Zone Management.
2. Click the Zone Name for the zone you want to delegate. Zone details and a list of
records appear.
3. Use the Type sort filter to locate the NS records for your zone.
4. Note the name servers in the RDATA field within each NS record.
You can use the noted name servers to change your domain's DNS delegation. Refer to your
registrar's documentation for instructions.
Oracle Cloud Infrastructure normalizes all RDATA into the most machine readable format. The
returned presentation of your RDATA may differ from its initial input.
Example:
The RDATA for the ALIAS, CNAME, DNAME, MX, and NS record types may contain one or more
absolute domain names. If the specified RDATA for one of these record types does not end in
a dot or period to represent the root, the period will be added.
You can use various DNS libraries to normalize your RDATA before input.
Go DNS Library in Go
Java dnsjava
Python dnspython
A
An address record used to point a hostname to an IPv4 address. For more information
about A records, see RFC 1035.
AAAA
An address record used point a hostname at an IPv6 address. For more information about
AAAA records, see RFC 3596.
ALIAS
A private pseudo-record that allows CNAME functionality at the apex of a zone.
CAA
A Certification Authority Authorization record allows a domain name holder to specify one
or more Certification Authorities authorized to issue certificates for that domain. For more
information about CAA records, see RFC 6844.
CDNSKEY
A Child DNSKEY moves a CDNSSEC key from a child zone to a parent zone. The
information provided in this record must match the CDNSKEY information for your domain
at your other DNS provider. This record is automatically created if you enable DNSSEC on
a primary zone in Oracle Cloud Infrastructure DNS. For more information about CDNSKEY,
see RFC 7344.
CDS
A Child Delegation Signer record is a child copy of a DS record, for transfer to a parent
zone. For more information about CDS records, see RFC 7344.
CERT
A Certificate record stores public key certificates and related certificate revocation lists in
the DNS. For more information about CERT records, see RFC 2538 and RFC 4398.
CNAME
A Canonical Name record identifies the canonical name for a domain. For more
information about CNAME records, see RFC 1035.
CSYNC
A Child-to-Parent Synchronization record syncs records from a child zone to a parent
zone. For more information about CNAME records, see RFC 7477.
DHCID
A DHCP identifier record provides a way to store DHCP client identifiers in the DNS to
eliminate potential hostname conflicts within a zone. For more information about DHCID,
see RFC 4701.
DKIM
A Domain Keys Identified Mail is a special TXT record set up specifically to supply a public
key used to authenticate arriving mail for a domain. For more information about DKIM
records, see RFC 6376.
DNAME
A Delegation Name record has similar behavior to a CNAME record, but allows you to map
an entire subtree beneath a label to another domain. For more information about DNAME
records, see RFC 6672.
DNSKEY
A DNS Key record documents public keys used for DNSSEC. The information in this record
must match the DNSKEY information for your domain at your other DNS provider. For
more information about DNSKEY records, see RFC 4034.
DS
A Delegation Signer record resides at the top-level domain and points to a child zone's
DNSKEY record. DS records are created when DNSSEC security authentication is added to
the zone. For more information about DS records, see RFC 4034.
IPSECKEY
An IPSec Key record stores public keys for a host, network, or application to connect to IP
security (IPSec) systems. For more information on IPSECKEY records, see RFC 4025.
KEY
A Key record stores a public key that is associated with a domain name. Currently only
used by SIG and TKEY records. IPSECKEY and DNSKEY have replaced key for use in IPSec
and DNSSEC, respectively. For more information about KEY records, see RFC 4025.
KX
A Key Exchanger record identifies a key management agent for the associated domain
name with some cryptographic systems (not including DNSSEC). For more information
about KX records, see RFC 2230.
LOC
A Location record stores geographic location data of computers, subnets, and networks
within the DNS. For more information about LOC records, see RFC 1876.
MX
A Mail Exchanger record defines the mail server accepting mail for a domain. MX records
must point to a hostname. MX records must not point to a CNAME or IP address. For more
information about MX records, see RFC 1035.
NS
A Nameserver record lists the authoritative nameservers for a zone. Oracle Cloud
Infrastructure DNS automatically generates NS records at the apex of each new primary
zone. For more information about NS records, see RFC 1035.
PTR
A Pointer record reverse maps an IP address to a hostname. This behavior is the opposite
of an A Record, which forward maps a hostname to an IP address. PTR records are
commonly found in reverse DNS zones. For more information about PTR records, see RFC
1035.
PX
A resource record used in X.400 mapping protocols. For more information about PX
records, see RFC 822 and RFC 2163.
SOA
The Oracle Cloud Infrastructure DNS automatically generates an SOA record when a zone
is created. For more information about SOA records, see RFC 1035.
SPF
A Sender Policy Framework record is a special TXT record used to store data designed to
detect email spoofing. For more information about SPF records, see RFC 4408.
SRV
A Service Locator record allows administrators to use several servers for a single domain.
For more information about SRV records, see RFC 2782.
SSHFP
An SSH Public Key Fingerprint record publishes SSH public host key fingerprints using the
DNS. For more information about SSHFP records, see RFC 6594.
TLSA
A Transport Layer Security Authentication record associates a TLS server certificate, or
public key, with the domain name where the record is found. This relationship is called a
TLSA certificate association. For more information about TLSA records, see RFC 6698.
TXT
A Text record holds descriptive, human readable text, and can also include non-human
readable content for specific uses. It is commonly used for SPF records and DKIM records
that require non-human readable text items. For more information about TXT records, see
RFC 1035.
This is an example of a zone file downloaded from Oracle Cloud Infrastructure DNS.
$ORIGIN example.com.
@ 3600 SOA ns1.p30.oraclecloud.net. (
zone-admin.dyndns.com. ; address of responsible party
2016072701 ; serial number
3600 ; refresh period
600 ; retry period
604800 ; expire time
Note
Record Classes
$ORIGIN indicates a DNS node tree and will typically start a DNS zone file. Any host labels
below the origin will append the origin hostname to assemble a fully qualified hostname. Any
host label within a record that uses a fully qualified domain terminating with an ending period
will not append the origin hostname.
Example: With $ORIGIN example.com., any record where the host label field is not followed
by a period, example.com. will be appended to them.
The “@” symbol is a special label that indicates the $ORIGIN should replace the “@” symbol.
This is typically used for the apex of a zone.
SOA Record – The $ORIGIN is followed by the zone’s Start Of Authority (SOA) record. An
SOA record is required for each zone. It contains the name of the zone, the e-mail address of
the party responsible for administering the domain’s zone file, the current serial number of
the zone, the primary nameserver of the zone, and various timing elements (measured in
seconds).
l Primary Name Server – The nameserver that contains the original zone file and not
an AXFR transferred copy.
l Hostmaster Email – Address of the party responsible for the zone. A period “.” is used
in place of an “@” symbol. For email addresses that contain periods, replace the periods
with a slash “/”.
l Serial Number – Version number of the zone. The serial number will increase with
each subsequent update to your zone.
l Time To Refresh – How long a nameserver should wait prior to checking for a serial
number increase within the primary zone file, in seconds. An increased serial number
detected by a secondary DNS nameserver means a transfer is needed to sync your
records. Only applies to zones using secondary DNS.
l Time To Retry – How long a nameserver should wait prior to retrying to update a zone
after a failed attempt, in seconds. Only applies to zones using secondary DNS.
l Time To Expire – How long a nameserver should wait prior to considering data from a
secondary zone invalid and stop answering queries for that zone, in seconds. Only
applies to zones using secondary DNS.
l Minimum TTL – Minimum Time To Live (TTL). How long a nameserver or resolver
should cache a negative response, in seconds.
A zone file is a collection of resource records with each record entry described in the following
sequence:
l Host Label – A host label helps to define the hostname of a record and whether the
$ORIGIN hostname will be appended to the label. Fully qualified hostnames terminated
by a period will not append the origin.
l TTL – The Time To Live (TTL) is the amount of time that a DNS record will be cached by
an outside DNS server or resolver, in seconds.
l Record Class – There are three classes of DNS records: IN (Internet), CH (Chaosnet),
and HS (Hesiod). Oracle Cloud Infrastructure DNS only uses the IN class of records.
l Record Type – The type of a record, such as CNAME, AAAA, or TXT.
l Record Data – The data within a DNS answer, such as an IP address, hostname, or
other information. Different record types will contain different types of record data.
GoDaddy.com exports zone files in a proprietary format. To get the Oracle Cloud
Infrastructure DNS service to correctly import a zone file exported from GoDaddy.com, you
must directly alter the file. Follow these instructions to update the zone file.
4. Once the file has been amended, save the changes to the file and use the zone import
function to import the file into your DNS configuration. For more information about zone
import, see Managing DNS Zones.
Note
Example:
This is an example of a zone file exported from GoDaddy.com. The code in bold is the code
that needs to be removed from the file for it to be eligible for import into Oracle Cloud
Infrastructure DNS.
Tip
Domain: example.com
; Exported (y-m-d hh:mm:ss): 2019-01-10 13:05:04
;
; This file is intended for use for informational and archival
; MX Records
@ 604800 IN MX 10 amlxe.l.google.com.
@ 604800 IN MX 10 aplxe.l.google.com.
; TXT Records
@ 3600 IN TXT "google-site-verification=3J82-80dbMyCo5Q5C1G11JszeOnZPGCSYlHcPcXg"
@ 3600 IN TXT "google-site-verification=eS_QPYLE_W4nduSrlN-cddxG7ZqOnB743xsbX918"
Below is an example of an amended zone file ready to import into Oracle Cloud Infrastructure
DNS. The code in bold needs to be prepended to your zone file before import.
$ORIGIN example.com.
example.com. 3600 IN SOA ns41.domaincontrol.com. dns.net. (
2018122702
28800
7200
604800
3600
)
; A Records
@ 600 IN A 192.0.2.249
blog 10800 IN A 192.0.2.255
dev 1800 IN A 192.0.2.254
dev01 1800 IN A 192.0.2.253
dev02 1800 IN A 192.0.2.252
dev03 1800 IN A 192.0.2.251
dev04 1800 IN A 192.0.2.250abc123b432dc7785b7ef31f04f25c3e71 1800 IN CNAME
verify.bing.com.
; CNAME Records
akamai 600 IN CNAME www.example.edgekey.net.
email 3600 IN CNAME email.secureserver.net.
; MX Records
@ 604800 IN MX 10 amlxe.l.google.com.
@ 604800 IN MX 10 aplxe.l.google.com.
; TXT Records
@ 3600 IN TXT "google-site-verification=3J82-80dbMyCo5Q5C1GM8os1VYVEOnZPGCSYlHcPcXg"
@ 3600 IN TXT "google-site-verification=eS_QPYLE_W4nduSrlN-cddxG7ZqOnB7k7uIG7qrsyu8"
l Redirect all HTTP traffic for an entire zone to another zone. For example, if a company
owns example.net and example.com, HTTP Redirect lets the company redirect all HTTP
traffic for example.net to example.com. This is a one-to-one mapping; wildcards are
not supported.
l Redirect a specific subdomain to an HTTP URL. For example, test.example.com can be
redirected to http://example.net/test/test.php.
l Redirect a subdomain to a URL with a port number. For example, camera.example.com
can be redirected to http://office.example.com:8080 so a user can view their camera
system without typing in the port number each time.
l Permanently redirect a domain name that has been deprecated by displaying a 301
response code. Permanently redirecting a domain name informs search engines and
browsers what to do with the information.
To work with HTTP Redirects, you need to have a user login to the Console, and your user
needs sufficient authority (by way of an IAM policy) to perform all the instructions that follow.
If your user is in the Administrators group, you have the required authority.
If your user is not, then a policy like this would allow a specific group to manage HTTP
Redirects:
Allow group <GroupName> to manage http-redirects in compartment <CompartmentName>
If you're new to policies, see Getting Started with Policies and Common Policies. For more
details about policies for HTTP Redirect, see Details for the WAF Service.
and will be replaced with the query component of the request URL (including
a leading "?" if the request URL includes a query component).
l Response Code: The response code that is returned with the redirect. If your
website was permanently moved to the redirection URL and you want it to be
indexed by search engines, select 301 - Moved Permanently. If you want to
indicate that the URL has been temporarily changed to a different address, select
302 - Found.
l Create DNS Record: Select this check box to create an associated ALIAS record
for the redirect in the specified zone. If a record for the zone specified already
exists, the DNS record will not be created.
l ALIAS TTL in Seconds - The Time to Live for the ALIAS record before a new
ALIAS record is retrieved. The default value is 300.
l Tags: Optionally, you can apply 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.
5. Click Create. The redirect zone is added to the redirects list.
l GetHttpRedirect
l ListHttpRedirects
l CreateHttpRedirect
l UpdateHttpRedirect
l DeleteHttpRedirect
l ChangeHttpRedirectCompartment
should apply tags, skip this option (you can apply tags later) or ask your
administrator.
4. Click Create TSIG Key. The TSIG key details appear.
Note
1. Open the navigation menu. Under Core Infrastructure, go to Networking and click
TSIG Keys.
2. Find the TSIG key in the list, click the Actions icon (three dots), and then click Delete.
3. In the confirmation dialog box, click Delete.
TSIG Keys.
2. In the Scope section, select a compartment.
3. Find the TSIG key in the list, click the Actions icon (three dots), and then click Move
Resource.
4. Choose the destination compartment from the list.
5. Click Move Resource.
For more information, see Managing Compartments.
l ListTsigKeys
l CreateTsigKey
l GetTsigKey
l UpdateTsigKey
l DeleteTsigKey
l ChangeTsigKeyCompartment
Note
Using dig
Before using BIND's dig tool, you must access or install dig on your system. Once you have
access to dig, you can use dig to test your DNS.
Note
2. Extract the downloaded file and install BIND in the following directory: C:\Program
Files\ISC BIND 9. Select the Tools Only check box.
3. Once BIND is installed, on the Windows menu open the Control Panel, and then open
your System properties.
4. On the Advanced tab, click Environment Variables.
5. Under System Variables, select Path, and then click Edit.
6. At the end of the path in the Edit System Variable window, add C:\Program Files\ISC
BIND 9\bin, and then click OK.
7. In the Edit Variables window, click OK. In the System properties window, click OK.
l Question section: The query made to the DNS. In this example, we asked for the first
available A record for the hostname, oracle.com.
l Answer section: The first available answer for the query made to the DNS. In this
example, we received the A record for the IP address 137.254.16.101.
l Authority section: The authoritative nameservers from which the answer to the query
was received. These nameservers house the zones for a domain.
l Additional section: Additional information the resolver may need but not the answer
to the query.
dig Commands
dig Returns any A record found within the queried dig oracle.com
[hostname] hostname's zone.
dig Returns the records of that type found within dig oracle.com MX
[hostname] the queried hostname's zone.
[record
type]
dig Adding +trace instructs dig to resolve the dig dyn.com +trace
[hostname] query from the root nameserver downwards
+trace and to report the results from each query
step.
STEERING POLICIES
A framework to define the traffic management behavior for your zones. Steering policies
contain rules that help to intelligently serve DNS answers.
ATTACHMENTS
Allows you to link a steering policy to your zones. An attachment of a steering policy to a
zone occludes all records at its domain that are of a covered record type, constructing
DNS responses from its steering policy rather than from those domain's records. A
domain can have at most one attachment covering any given record type.
RULES
The guidelines steering policies use to filter answers based on the properties of a DNS
request, such as the requests geo-location or the health of your endpoints.
ANSWERS
Answers contain the DNS record data and metadata to be processed in a steering policy.
To access the Console, you must use a supported browser. You can use the Console link at the
top of this page to go to the sign-in page. Enter your tenancy, user name, and your password.
An administrator in your organization needs to set up groups, compartments, and policies that
control which users can access which services, which resources, and the type of access. For
example, the policies control who can create new users, create and manage the cloud
network, launch instances, create buckets, download objects, etc. For more information, see
Getting Started with Policies. For specific details about writing policies for each of the
different services, see Policy Reference.
If you’re a regular user (not an administrator) who needs to use the Oracle Cloud
Infrastructure resources that your company owns, contact your administrator to set up a user
ID for you. The administrator can confirm which compartment or compartments you should be
using.
If you're new to policies, see Getting Started with Policies and Common Policies. For more
details about policies for Traffic Management Steering Policies, see Details for the Traffic
Management Steering Policies Service.
Each service in Oracle Cloud Infrastructure integrates with IAM for authentication and
authorization, for all interfaces (the Console, SDK or CLI, and REST API).
An administrator in your organization needs to set up groups, compartments, and policies that
control which users can access which services, which resources, and the type of access. For
example, the policies control who can create new users, create and manage the cloud
network, launch instances, create buckets, download objects, etc. For more information, see
Getting Started with Policies. For specific details about writing policies for each of the
different services, see Policy Reference.
If you’re a regular user (not an administrator) who needs to use the Oracle Cloud
Infrastructure resources that your company owns, contact your administrator to set up a user
ID for you. The administrator can confirm which compartment or compartments you should be
using.
The following list describes the components used to build a Traffic Management Steering
Policy.
STEERING POLICIES
An overall framework to define the traffic management behavior for your zones. Steering
policies contain rules that help to intelligently serve DNS answers.
ATTACHMENTS
Allows you to link a steering policy to your zones. An attachment of a steering policy to a
zone occludes all records at its domain that are of a covered record type, constructing
DNS responses from its steering policy rather than from those domain's records. A
domain can have at most one attachment covering any given record type.
RULES
The guidelines steering policies use to filter answers based on the properties of a DNS
request, such as the requests geo-location or the health of your endpoints.
ANSWERS
Answers contain the DNS record data and metadata to be processed in a steering policy.
TEMPLATES
Templates are predefined rule sequences that create a policy type and its intended
behavior. Example: The FAILOVER template determines answers by checking DNS query
against a FILTER rule first, then the following rules in succession: HEALTH, PRIORITY, and
LIMIT. This gives the domain dynamic failover capability. Policies that define the
template field with any policy other than CUSTOM, must follow the rule sequence outlined
for that policy type, otherwise, a 400 status code error will be returned upon policy
creation.
CASES
A rule may optionally include a sequence of cases defining alternate configurations for
how it should behave during processing for any given DNS query. When a rule has no
sequence of cases, it is always evaluated with the same configuration during processing.
When a rule has an empty sequence of cases, it is always ignored during processing.
When a rule has a non-empty sequence of cases, its behavior during processing is
configured by the first matching case in the sequence. A rule case with no caseCondition
always matches. A rule case with a caseCondition matches only when that expression
evaluates to true for the given query.
The following section explains the rule configuration for each type of steering policy template
followed by an example POST request (CreateSteeringPolicy) displaying how to configure
each template.
FAILOVER
Failover policies allow you to prioritize the order in which you want answers served in a
policy (for example, Primary and Secondary). Oracle Cloud Infrastructure Health Checks
are leveraged to determine the health of answers in the policy. If the Primary Answer is
determined to be unhealthy, DNS traffic will automatically be steered to the Secondary
Answer. Each of the following rules must be defined in the order specified below in the
rules field of your request body when using a FAILOVER template:
"rules": [
{
"ruleType": "FILTER",
"defaultAnswerData": [
{
"answerCondition": "answer.isDisabled != true",
"shouldKeep": true
}
]
},
{
"ruleType": "HEALTH"
},
{
"ruleType": "PRIORITY",
"defaultAnswerData": [
{
"answerCondition": "answer.pool == 'primary'",
"value": 1
},
{
"answerCondition": "answer.pool == 'secondary'",
"value": 99
}
]
},
{
"ruleType": "LIMIT",
"defaultCount": 1
}
]
}
LOAD_BALANCE
Load Balancer policies allow distribution of traffic across multiple endpoints. Endpoints
can be assigned equal weights to distribute traffic evenly across the endpoints or custom
weights may be assigned for ratio load balancing. Oracle Cloud Infrastructure Health
Checks are leveraged to determine the health of the endpoint. DNS traffic will be
automatically distributed to the other endpoints, if an endpoint is determined to be
unhealthy. Each of the following rules must be defined in the order specified below in the
rules field of your request body when using a LOAD_BALANCE template:
],
"rules": [
{
"ruleType": "FILTER",
"defaultAnswerData": [
{
"answerCondition": "answer.isDisabled != true",
"shouldKeep": true
}
]
},
{
"ruleType": "HEALTH"
},
{
"ruleType": "WEIGHTED",
"defaultAnswerData": [
{
"answerCondition": "answer.name == 'server1'",
"value": 99
},
{
"answerCondition": "answer.name == 'server2'",
"value": 1
}
]
},
{
"ruleType": "LIMIT",
"defaultCount": 1
}
]
}
ROUTE_BY_GEO
the order specified below in the rules field of your request body when using a ROUTE_BY_
GEO template:
"pool": "US"
},
{
"name": "EU Server 1",
"rtype": "A",
"rdata": "192.168.0.4",
"pool": "EU"
},
{
"name": "EU Server 2",
"rtype": "A",
"rdata": "192.168.0.5",
"pool": "EU"
},
{
"name": "rest of world 1",
"rtype": "A",
"rdata": "203.0.113.2",
"pool": "Global"
},
{
"name": "rest of world 2",
"rtype": "A",
"rdata": "203.0.113.3",
"pool": "Global"
}
],
"rules": [
{
"ruleType": "FILTER",
"defaultAnswerData": [
{
"answerCondition": "answer.isDisabled != true",
"shouldKeep": true
}
]
},
{
"ruleType": "HEALTH"
},
{
"ruleType": "PRIORITY",
"cases": [
{
"caseCondition": "query.client.geoKey in (geoKey '6255149')",
"answerData": [
{
"answerCondition": "answer.pool == 'US'",
"value": 1
},
{
"answerCondition": "answer.pool == 'EU'",
"value": 2
},
{
"answerCondition": "answer.pool == 'Global'",
"value": 3
}
]
},
{
"caseCondition": "query.client.geokey in (geokey '6255148')",
"answerdata": [
{
"answerCondition": "answer.pool == 'EU'",
"value": 1
},
{
"answerCondition": "answer.pool == 'US'",
"value": 2
},
{
"answerCondition": "answer.pool == 'Global'",
"value": 3
}
]
},
{
"answerData": [
{
For a list of geographic keys to use in the geokey field, see Traffic Management Steering
Policy geokeys.
ROUTE_BY_ASN
ASN-based steering policies enable you to steer DNS traffic based on Autonomous System
Numbers (ASN). DNS queries originating from a specific ASN or set of ASNs can be
steered to a specified endpoint. Each of the following rules must be defined in the order
specified below in the rules field of your request body when using a ROUTE_BY_ASN
template:
"rtype": "A",
"rdata": "203.0.113.2",
"pool": "Other"
}
],
"rules": [
{
"ruleType": "FILTER",
"defaultAnswerData": [
{
"answerCondition": "answer.isDisabled != true",
"shouldKeep": true
}
]
},
{
"ruleType": "PRIORITY",
"cases": [
{
"caseCondition": "query.client.asn == 3",
"answerData": [
{
"answerCondition": "answer.pool == 'ABC'",
"value": 1
},
{
"answerCondition": "answer.pool == 'DEF'",
"value": 2
},
{
"answerCondition": "answer.pool == 'Other'",
"value": 3
}
]
},
{
"caseCondition": "query.client.asn == 16591",
"answerdata": [
{
"answerCondition": "answer.pool == 'DEF'",
"value": 1
},
{
"answerCondition": "answer.pool == 'ABC'",
"value": 2
},
{
"answerCondition": "answer.pool == 'Other'",
"value": 3
}
]
},
{
"answerData": [
{
"answerCondition": "answer.pool == 'Other'",
"value": 1
},
{
"answerCondition": "answer.pool == 'ABC'",
"value": 2
},
{
"answerCondition": "answer.pool == 'DEF'",
"value": 3
}
]
}
]
},
{
"ruleType": "LIMIT",
"defaultCount": 1
}
]
}
ROUTE_BY_IP
IP Prefix-based steering policies enable customers to steer DNS traffic based on the IP
Prefix of the originating query. Each of the following rules must be defined in the order
specified below in the rules field of your request body when using a ROUTE_BY_IP
template:
"pool": "DEF"
},
{
"name": "Other",
"rtype": "A",
"rdata": "203.0.113.2",
"pool": "Other"
}
],
"rules": [
{
"ruleType": "FILTER",
"defaultAnswerData": [
{
"answerCondition": "answer.isDisabled != true",
"shouldKeep": true
}
]
},
{
"ruleType": "PRIORITY",
"cases": [
{
"caseCondition": "query.client.address in (subnet '10.0.3.0/24')",
"answerData": [
{
"answerCondition": "answer.pool == 'ABC'",
"value": 1
},
{
"answerCondition": "answer.pool == 'DEF'",
"value": 2
},
{
"answerCondition": "answer.pool == 'Other'",
"value": 3
}
]
},
{
CUSTOM
Custom policies allow you to create complex policies combining the capabilities of
failover, load balancing, geolocation, ASN and IP prefix steering. Custom templates to not
require a regimented sequence of rules and it is recommended to contact Oracle Cloud
Infrastructure support before creating a custom policy.
Rule Types
FILTER
Uses boolean data associated with answers, keeping answers only if the rule's
shouldKeep value is true.
HEALTH
Utilizes Oracle Cloud Health Check monitors to determine the health of your endpoints and
add and remove answers from your policy as needed. A health check monitor must be
referenced in a health rule to have an effect on the policy. For more information about
Health Checks, see Health Checks.
WEIGHTED
Uses a number between 0 and 255 used to determine how often an answer will be served
in relation to other answers. Answers with higher values are more likely to be returned.
PRIORITY
Uses an integer associated with each answer to sort answers from lowest to highest
value. Example: An answer with a priority value of 1 would be returned before an answer
with a priority value of 10 in the list of answers. Answers that do not have a priority value
assigned to them will be moved to the end of the list of answers.
LIMIT
Uses a count property to filter away all but the first answers in the list.
Policy Types
FAILOVER
Failover policies allow you to prioritize the order in which you want answers served in a
policy (for example, Primary and Secondary). Oracle Cloud Infrastructure Health Checks
are leveraged to determine the health of answers in the policy. If the Primary Answer is
determined to be unhealthy, DNS traffic will automatically be steered to the Secondary
Answer.
LOAD BALANCER
Load Balancer policies allow distribution of traffic across multiple endpoints. Endpoints
can be assigned equal weights to distribute traffic evenly across the endpoints or custom
weights may be assigned for ratio load balancing. Oracle Cloud Infrastructure Health
Checks are leveraged to determine the health of the endpoint. DNS traffic will be
automatically distributed to the other endpoints, if an endpoint is determined to be
unhealthy.
GEOLOCATION STEERING
Geolocation steering policies distribute DNS traffic to different endpoints based on the
location of the end user. Customers can define geographic regions composed of
originating continent, countries or states/provinces (North America) and define a separate
endpoint or set of endpoints for each region.
ASN STEERING
ASN steering policies enable you to steer DNS traffic based on Autonomous System
Numbers (ASN). DNS queries originating from a specific ASN or set of ASNs can be
steered to a specified endpoint.
IP PREFIX STEERING
IP Prefix steering policies enable customers to steer DNS traffic based on the IP Prefix of
the originating query.
This section describes several typical scenarios for using Traffic Management Steering
Policies.
BASIC FAILOVER
You can leverage Traffic Management Steering Policies to provide automated failover between
primary and secondary servers.
CLOUD MIGRATION
Weighted load balancing supports controlled migration from your data center to Oracle Cloud
Infrastructure servers. You can steer a small amount of traffic (1%) to your new resources in
the cloud to verify everything is working as expected. You can then increase the ratios until
you are comfortable with fully migrating all DNS traffic to the cloud.
You can configure load balancing pools of multiple servers. Traffic Management Steering
Policies can automatically distribute DNS traffic across the set of servers. Health Checks may
also be used and traffic will be automatically redirected to healthy servers, if a server is
determined to be unhealthy.
HYBRID ENVIRONMENTS
Since Traffic Management Steering Policies is an agnostic service, it may be used to not only
steer traffic to Oracle Cloud Infrastructure resources, but can also be used to steer traffic to
any publicly exposed (internet resolvable) resources, including other cloud providers and
enterprise data centers.
You can divide your global users into geographically defined regions (for example,
state/province level in NA, country level for rest of world) and steer customers to specified
resources based on their location. This helps to ensure global, high performing internet
resolution, and supports functions such as ring fencing. For example, keeping traffic from
China in China and block traffic outside of China into China.
CANARY TESTING
Leveraging IP Prefix steering, you can configure policies to serve different responses for your
internal users versus external users.
ZERO-RATING S ERVICES
ASN steering conditional steering based on the originating enterprise, mobile operator or
other communications provider in support of various commercial agreements that may be in
place. Essentially, preferred ASNs can be directed to free resources, while all other traffic can
be directed to paid resources.
l Policy TTL: The Time to Live for responses from the steering policy. If not
specified, the system will set this value on the steering policy.
l Maximum Answer Count: The maximum number of answers returned for the
policy. For priority-based policies, the first valid answer is returned.
l Answer Pool(s): Answer pools contain the group of answers that will be served
in response to DNS queries.
o Answer Pool Name: A user-friendly name for the answer pool, unique
within the steering policy. Avoid entering confidential information.
o Name: A unique name to identify the answer. Avoid entering confidential
information.
o Type: The record type that will be provided as the answer.
o RDATA: A valid domain name or IP address to add as an answer.
o Weight: A number between 0 and 255 used to determine how often an
answer is served in relation to other answers. Answers with higher values
are more likely to be served.
o Eligible: Select the check box to indicate that the answer is available
within the pool to be used in response to queries. Alternatively, select Mark
pool answers eligible or Mark pool answers ineligible from the
Actions drop-down menu.
l Pool Priority: Failover priority rules specify the priority of answers that are
served in a policy. If the primary answer is unavailable, traffic is steered to the
next answer in the list.
o Pool: Select the priority in which the answers are served.
l Attach Health Check: Select an existing Health Check to be included as part of
the policy, add a new one, or select None.
l Attach Domain(s): The domain name and domain OCID you want to attach to
the policy. Additional domains can be added in this section.
5. Click Create Policy.
l Maximum Answer Count: The maximum number of answers returned for the
policy. For priority-based policies, the first valid answer is returned.
l Answer Pool(s): Answer pools contain the group of answers that will be served
in response to DNS queries.
o Answer Pool Name: A user-friendly name for the answer pool, unique
within the steering policy. Avoid entering confidential information.
o Name: A unique name to identify the answer. Avoid entering confidential
information.
o Type: The record type that will be provided as the answer.
o RDATA: A valid domain name or IP address to add as an answer.
o Eligible: Select the check box to indicate that the answer is available
within the pool to be used in response to queries. Alternatively, select Mark
pool answers eligible or Mark pool answers ineligible from the
Actions drop-down menu.
l ASN Steering Rules: ASN steering rules specify the priority of answers that are
served in a policy. If the primary answer is unavailable, traffic is steered to the
next answer in the list.
o ASN: Enter an Autonomous System Number (ASN) that will be used to
distribute DNS traffic.
o Pool Priority: Select the priority in which the answers are served.
o Global Catch-all: Adding a global catch-all allows you to specify answer
pools for queries that do not match any of the specified rules you have
added. Click Add Global Catch-all and select the pool priorities.
l Attach Health Check: Select an existing Health Check to be included as part of
the policy, add a new one, or select None.
l Attach Domain(s): The domain name and domain OCID you want to attach to
the policy. Additional domains can be added in this section.
5. Click Create Policy.
To update a policy
1. Open the navigation menu. Under Core Infrastructure, go to Networking and click
Traffic Management Steering Policies.
2. Click the Policy Name you want to update. Policy information and a list of attached
domains appear.
Tip
3. Click Edit.
4. Make the needed changes, and then click Save.
Tip
Tip
3. For the attached domain you want to edit, click the Actions icon (three dots), and then
click Edit Attached Domain.
4. In the Attached Domain(s) dialog box, enter the domain and select a zone.
5. Click Save.
To delete a policy
1. Open the navigation menu. Under Core Infrastructure, go to Networking and click
Traffic Management Steering Policies.
2. Select the check box for the policy you want to delete.
3. Click Delete. The policy is staged for deletion.
4. Click Publish Changes to delete the policy.
5. In the confirmation dialog box, click Publish Changes.
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.
For more information about managing steering policies using the API, see Traffic Management
Steering Policies API Guide.
l CreateSteeringPolicy
l ListSteeringPolicies
l GetSteeringPolicy
l UpdateSteeringPolicy
l DeleteSteeringPolicy
l CreateSteeringPolicyAttachment
l ListSteeringPolicyAttachments
l GetSteeringPolicyAttachment
l UpdateSteeringPolicyAttachment
l DeleteSteeringPolicyAttachment
Continent geokeys
Africa 6255146
Antarctica 6255152
Asia 6255147
Europe 6255148
Oceania 6255151
Country geokeys
Afghanistan(AF) 1149361
Albania(AL) 783754
Algeria(DZ) 2589581
Andorra(AD) 3041565
Angola(AO) 3351879
Anguilla(AI) 3573511
Antarctica(AQ) 6697173
Argentina(AR) 3865483
Armenia(AM) 174982
Aruba(AW) 3577279
Australia(AU) 2077456
Austria(AT) 2782113
Azerbaijan(AZ) 587116
Bahamas(BS) 3572887
Bahrain(BH) 290291
Bangladesh(BD) 1210997
Barbados(BB) 3374084
Belarus(BY) 630336
Belgium(BE) 2802361
Belize(BZ) 3582678
Benin(BJ) 2395170
Bermuda(BM) 3573345
Bhutan(BT) 1252634
Bolivia(BO) 3923057
Botswana(BW) 933860
Brazil(BR) 3469034
Brunei(BN) 1820814
Bulgaria(BG) 732800
Burundi(BI) 433561
Cambodia(KH) 1831722
Cameroon(CM) 2233387
Canada(CA) 6251999
Chad(TD) 2434508
Chile(CL) 3895114
China(CN) 1814991
Colombia(CO) 3686110
Comoros(KM) 921929
Congo(CG) 2260494
Croatia(HR) 3202326
Cuba(CU) 3562981
Curacao(CW) 7626836
Cyprus(CY) 146669
Denmark(DK) 2623032
Djibouti(DJ) 223816
Dominica(DM) 3575830
Ecuador(EC) 3658394
Egypt(EG) 357994
El Salvador(SV) 3585968
Eritrea(ER) 338010
Estonia(EE) 453733
Ethiopia(ET) 337996
Fiji(FJ) 2205218
Finland(FI) 660013
France(FR) 3017382
Gabon(GA) 2400553
Gambia(GM) 2413451
Georgia(GE) 614540
Germany(DE) 2921044
Ghana(GH) 2300660
Gibraltar(GI) 2411586
Greece(GR) 390903
Greenland(GL) 3425505
Grenada(GD) 3580239
Guadeloupe(GP) 3579143
Guam(GU) 4043988
Guatemala(GT) 3595528
Guernsey(GG) 3042362
Guinea(GN) 2420477
Guinea-Bissau(GW) 2372248
Guyana(GY) 3378535
Haiti(HT) 3723988
Honduras(HN) 3608932
Hungary(HU) 719819
Iceland(IS) 2629691
India(IN) 1269750
Indonesia(ID) 1643084
Iran(IR) 130758
Iraq(IQ) 99237
Ireland(IE) 2963597
Israel(IL) 294640
Italy(IT) 3175395
Jamaica(JM) 3489940
Japan(JP) 1861060
Jersey(JE) 3042142
Jordan(JO) 248816
Kazakhstan(KZ) 1522867
Kenya(KE) 192950
Kiribati(KI) 4030945
Kuwait(KW) 285570
Kyrgyzstan(KG) 1527747
Laos(LA) 1655842
Latvia(LV) 458258
Lebanon(LB) 272103
Lesotho(LS) 932692
Liberia(LR) 2275384
Libya(LY) 2215636
Liechtenstein(LI) 3042058
Lithuania(LT) 597427
Luxembourg(LU) 2960313
Macau(MO) 1821275
Macedonia(MK) 718075
Madagascar(MG) 1062947
Malawi(MW) 927384
Malaysia(MY) 1733045
Maldives(MV) 1282028
Mali(ML) 2453866
Malta(MT) 2562770
Martinique(MQ) 3570311
Mauritania(MR) 2378080
Mauritius(MU) 934292
Mayotte(YT) 1024031
Mexico(MX) 3996063
Micronesia(FM) 2081918
Moldova(MD) 617790
Monaco(MC) 2993457
Mongolia(MN) 2029969
Montenegro(ME) 3194884
Montserrat(MS) 3578097
Morocco(MA) 2542007
Mozambique(MZ) 1036973
Myanmar(MM) 1327865
Namibia(NA) 3355338
Nauru(NR) 2110425
Nepal(NP) 1282988
Netherlands(NL) 2750405
Nicaragua(NI) 3617476
Niger(NE) 2440476
Nigeria(NG) 2328926
Niue(NU) 4036232
Norway(NO) 3144096
Oman(OM) 286963
Pakistan(PK) 1168579
Palau(PW) 1559582
Panama(PA) 3703430
Paraguay(PY) 3437598
Peru(PE) 3932488
Philippines(PH) 1694008
Pitcairn(PN) 4030699
Poland(PL) 798544
Portugal(PT) 2264397
Qatar(QA) 289688
Reunion(RE) 935317
Romania(RO) 798549
Russia(RU) 2017370
Rwanda(RW) 49518
Samoa(WS) 4034894
Senegal(SN) 2245662
Serbia(RS) 6290252
Seychelles(SC) 241170
Singapore(SG) 1880251
Slovakia(SK) 3057568
Slovenia(SI) 3190538
Somalia(SO) 51537
Spain(ES) 2510769
Sudan(SD) 366755
Suriname(SR) 3382998
Swaziland(SZ) 934841
Sweden(SE) 2661886
Switzerland(CH) 2658434
Syria(SY) 163843
Taiwan(TW) 1668284
Tajikistan(TJ) 1220409
Tanzania(TZ) 149590
Thailand(TH) 1605651
Togo(TG) 2363686
Tokelau(TK) 4031074
Tonga(TO) 4032283
Tunisia(TN) 2464461
Turkey(TR) 298795
Turkmenistan(TM) 1218197
Tuvalu(TV) 2110297
Uganda(UG) 226074
Ukraine(UA) 690791
Uruguay(UY) 3439705
Uzbekistan(UZ) 1512440
Vanuatu(VU) 2134431
Venezuela(VE) 3625428
Vietnam(VN) 1562822
Yemen(YE) 69543
Zambia(ZM) 895949
Zimbabwe(ZW) 878675
Alabama 4829764
Alaska 5879092
Arizona 5551752
Arkansas 4099753
California 5332921
Colorado 5417618
Connecticut 4831725
Delaware 4142224
Florida 4155751
Georgia 4197000
Hawaii 5855797
Idaho 5596512
Illinois 4896861
Indiana 4921868
Iowa 4862182
Kansas 4273857
Kentucky 6254925
Louisiana 4331987
Maine 4971068
Maryland 4361885
Massachusetts 6254926
Michigan 5001836
Minnesota 5037779
Mississippi 4436296
Missouri 4398678
Montana 5667009
Nebraska 5073708
Nevada 5509151
Ohio 5165418
Oklahoma 4544379
Oregon 5744337
Pennsylvania 6254927
Tennessee 4662168
Texas 4736286
Utah 5549030
Vermont 5242283
Virginia 6254928
Washington 5815135
Wisconsin 5279468
Wyoming 5843591
Alberta 5883102
Manitoba 6065171
Nunavut 6091732
Ontario 6093943
Quebec 6115047
Saskatchewan 6141242
Yukon 6185811
Oracle Cloud Infrastructure's Email Deliverability team manages the platform using key
deliverability metrics to ensure the best sending reputation possible for your emails.
The following items are provided to you when you send email using the Email Delivery
service:
l Unique mailbox provider SMTP configurations on our Mail Transfer Agents (MTA)
l Bounce collection
l User complaint collection
l Email authentication standards
l Deliverability performance
APPROVED SENDERS
it must be created in the other region. For example, if you create an approved sender in
the US West (Phoenix) region, you cannot send email through the US East (Ashburn)
region.
SUPPRESSION LIST
The Suppression List is included on your Email Delivery console user interface and from
the API. Email Delivery automatically adds email addresses with bounce codes showing
permanent failures or user complaints to the suppression list to protect your sender
reputation. Email Delivery will not send any messages to these recipients in the future.
l Complaints
l Hard bounces
l Repetitive soft bounces
l Manual entries
l List-unsubscribe requests
SPF AUTHENTICATION
Sender Policy Framework (SPF) is used by email receivers to detect email spoofing. Using
SPF, an email receiver can check if the Internet Protocol (IP) is explicitly authorized to send
for that domain. SPF is implemented by publishing a special TXT record to a domain's DNS
records. The TXT record declares which hosts are allowed to send mail on behalf of this
domain. Receiving mail servers check the SPF records of sending domains to verify that the
email's source IP address is authorized to send from that domain. Without SPF, a spam or
phishing email can be “spoofed” to appear that the email comes from a legitimate domain.
Domains that implement SPF are much more likely to block emails attempting to spoof your
domain. For an overview of how SPF works, see Sender Policy Framework. For details on
SPF record syntax, see SPF Record Syntax.
The sending application is not required to be located in the region where email is sent. For
example, if your sending application is located in a region where Email Delivery is not
currently available, you would configure email from one of the regions where it is available.
In the Console, change your region to an available region and create an approved sender.
When creating SMTP credentials, any region can be used, as identities are global assets.
Configure your application to send email to the region where you created the approved sender
using the SMTP credentials.
When Email Delivery is available in more regions, you can configure Email Delivery in the
same region as the sending application to improve performance.
If you want to start sending email from a new region, keep the following in mind:
To access the Console, you must use a supported browser. You can use the Console link at the
top of this page to go to the sign-in page. You are prompted to enter your cloud tenant, your
user name, and your password. For general information about using the API, see About the
API.
An administrator in your organization needs to set up groups, compartments, and policies that
control which users can access which services, which resources, and the type of access. For
example, the policies control who can create new users, create and manage the cloud
network, launch instances, create buckets, download objects, etc. For more information, see
Getting Started with Policies. For specific details about writing policies for each of the
different services, see Policy Reference.
If you’re a regular user (not an administrator) who needs to use the Oracle Cloud
Infrastructure resources that your company owns, contact your administrator to set up a user
ID for you. The administrator can confirm which compartment or compartments you should be
using.
Email Delivery supports the following authentication types for control plane operations
(management endpoint):
Note
Use the following regional endpoints for establishing SMTP connections for sending.
Monitoring Resources
You can monitor the health, capacity, and performance of your Oracle Cloud Infrastructure
resources by using metrics, alarms, and notifications. For more information, see Monitoring
Overview and Notifications Overview.
For information about available Email Delivery service metrics and how to view them, see
Email Delivery Metrics.
Customers that sign up for a free Oracle Cloud trial are limited to:
Note
Dedicated IP Availability
Email Delivery supports dedicated IPs which allow you to have control over your reputation.
Dedicated IPs are Oracle Cloud IP addresses that are reserved for your email sending. By
default, customer accounts are configured into tiered shared sending pools depending on your
email characteristics. Dedicated IPs are suggested for larger sending volumes. Dedicated IPs
may not be advised for lower or more sporadic email sending as this will not support a good
sending reputation, and therefore cause impact to your email deliverability.
Each customer's mail characteristics (volume, burst rates, reputation, etc.) will vary your
dedicated IP strategy. Our teams are trained on this subject and ready to support your
dedicated IP needs. Contact support to assist with this configuration.
Note
Note
If you're new to policies, see Getting Started with Policies and Common Policies. For more
details about policies for Email Delivery, see Details for the Email Service.
Permissions are required for managing and using approved senders and the suppression list.
For example:
Tagging Resources
You can apply tags to your resources to help you organize them according to your business
needs. You can apply tags at the time you create a resource, or you can update the resource
later with the desired tags. For general information about applying tags, see Resource Tags.
To view logs for events in the Email Delivery service, your user must be in a group with the
ability to view all of the Audit event logs in the tenancy. For more information, see Viewing
Audit Log Events.
When you use Email Delivery, we become your outbound email server. If you have an existing
email server, you can keep it and configure it to send through Email Delivery. The Email
Delivery service will take care of the feedback loops and platform reputation automatically.
Getting Started
This topic gives guidance on how to get started with Email Delivery. For complete details
about the service and its components, see Overview of the Email Delivery Service.
You can configure Oracle Cloud Infrastructure using the Console (a browser-based interface),
REST API, SDKs, CLI or Terraform.
Sending Email
To begin sending email with Email Delivery, complete the following steps:
Best Practice: A security best practice is to generate SMTP credentials for a new user
instead of your Console user that already has permissions assigned to it. For detailed
instructions on creating a user, see Adding Users.
Tip
6. Copy the user name and password for your records and click Close.
Set up permissions.
The new user must be assigned to a group with permissions to manage approved-senders
and suppressions.
l Name: A unique name for the policy. The name must be unique across all policies
in your tenancy. You cannot change this later.
l Description: A friendly description. You can change this later if you want to.
l Policy Versioning: Select Keep Policy Current if you'd like the policy to stay
current with any future changes to the service's definitions of verbs and
resources. Or if you'd prefer to limit access according to the definitions that were
current on a specific date, select Use Version Date and enter that date in format
YYYY-MM-DD format. For more information, see Policy Language Version.
l Statement: Enter the following policy statement:
Allow group <group name> to use approved-senders in compartment <compartment name>
For more information about policies and policy syntax, see Policy Basics.
l Tags: Optionally, you can apply 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.
5. Click Create.
Make sure to let the user know which compartment(s) they have access to.
an approved sender in the Phoenix (PHX) region, you cannot send email through the Ashburn
(IAD) region.
Best Practice: Approved senders should not be created in the root compartment. If
approved senders exist in the root compartment, you are required to create a policy to
manage approved senders in the entire tenant. Creating approved senders in a compartment
other than the root allows the policy to be specific to that compartment.
Tip
POST /20170907/senders
{
"compartmentId":
"ocid1.compartment.oc1..aaaaaaaat7uqcb6zoxvzoga4d4vh4dtweciavepacd3skz56atf3qp73d7fx",
"emailAddress": "[email protected]",
The Approved Senders section within the Console provides validation of an SPF record for
each of your approved senders.
To configure SPF
1. Open the navigation menu. Under Solutions and Platform, go to Email Delivery and
click Email Approved Senders.
2. Select the checkbox for the approved sender you want to view SPF details for and click
View SPF.
Tip
3. The Manage SPF dialog box appears indicating whether an SPF record for the approved
sender exists.
l If your domain does not currently have an SPF record, the information necessary
to add an SPF record in your DNS setup is displayed. See Managing DNS Service
Zones for instructions on adding a zone record in Oracle Cloud Infrastructure. If
your DNS setup resides with another provider, please reference their
documentation for adding a TXT record to your domain.
o In your DNS setup, create a TXT record and paste the following information
into the record based on the sending location:
SMTP Connection Endpoints
Use the following regional endpoints for establishing SMTP connections for sending.
l YNY: smtp.email.ap-chuncheon-1.oci.oraclecloud.com
l HYD: smtp.email.ap-hyderabad-1.oci.oraclecloud.com
l MEL: smtp.email.ap-melbourne-1.oci.oraclecloud.com
l BOM: smtp.email.ap-mumbai-1.oci.oraclecloud.com
l KIX: smtp.email.ap-osaka-1.oci.oraclecloud.com
l ICN: smtp.email.ap-seoul-1.oci.oraclecloud.com
l SYD: smtp.email.ap-sydney-1.oci.oraclecloud.com
l NRT: smtp.email.ap-tokyo-1.oci.oraclecloud.com
l YUL: smtp.email.ca-montreal-1.oci.oraclecloud.com
l YYZ: smtp.email.ca-toronto-1.oci.oraclecloud.com
l AMS: smtp.email.eu-amsterdam-1.oci.oraclecloud.com
l FRA: smtp.email.eu-frankfurt-1.oci.oraclecloud.com
l ZRH: smtp.email.eu-zurich-1.oci.oraclecloud.com
l JED: smtp.email.me-jeddah-1.oci.oraclecloud.com
l GRU: smtp.email.sa-saopaulo-1.oci.oraclecloud.com
l LHR: smtp.email.uk-london-1.oci.oraclecloud.com
l IAD: smtp.us-ashburn-1.oraclecloud.com
l PHX: smtp.us-phoenix-1.oraclecloud.com
TLS Requirements
Oracle maintains strict security policies and only accepts email traffic using Transport Layer
Security (TLS). Use of TLS 1.2 is mandatory to send email using Oracle Cloud Infrastructure.
l TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
l TLS_DHE_DSS_WITH_AES_256_CBC_SHA256
l TLS_RSA_WITH_AES_256_CBC_SHA256
l TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
l TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
l TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
l TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
l TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
l TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
Open the navigation menu. Under Solutions and Platform, go to Email Delivery and click
Email Configuration. The following information is displayed:
l Manage SMTP Credentials: Access your user credentials. Use the SMTP user
credentials (in plain text) when validating your connection.
l Server Name: Regional SMTP endpoint
l Port: Email Delivery supports TLS on port 25 or 587.
l Use Transport Layer Security (TLS): This field indicates if TLS, the standard means
of performing encryption in transit for email, is being used. Customers must encrypt
email while it is in transit to the Oracle Cloud Infrastructure Email Delivery service.
Encrypted emails are protected from being read during transit.
Tip
Suppression List
As you begin to send email, Email Delivery automatically adds email addresses with bounce
codes showing permanent failures or user complaints to the suppression list to protect your
sender reputation. Email Delivery will not send any messages to these recipients in the future.
Reasons for suppression currently include:
l Complaints
l Hard bounces
l Repetitive soft bounces
l Manual entries
l List-unsubscribe requests
To manually add an email address to the suppression list using the Console
1. Open the navigation menu. Under Solutions and Platform, go to Email Delivery and
click Email Suppression List.
2. Click Add Suppression.
To manually add an email address to the suppression list using the API
The following example shows how to add an email address to the suppression list. For more
information about managing the suppressions list, see GetSuppression and
DeleteSuppression.
POST /20170907/suppressions
{
"compartmentId":
"ocid1.compartment.oc1..aaaaaaaat7uqcb6zoxvzoga4d4vh4dtweciavepacd3skz56atf3qp73d7fx",
"emailAddress": "[email protected]",
You can access Oracle Cloud Infrastructure using the REST API. Instructions for the API are
included in topics throughout this guide. For a list of available SDKs, see SDKs and Other
Tools.
Regions
See Regions and Availability Domains for information on regions Email Delivery is available
in.
Limits
See Email Delivery Service Capabilities and Limits for information on new account and
enterprise account limits.
Best Practices
Volume Testing - In order to maintain our sender reputation and yours, testing at volume
needs to be done using the following best practice.
Deliverability - To help you learn and manage the habits that affect your sending reputation,
see Deliverability Best Practices.
Sending to Email Aliases - When sending email to an alias, the alias is considered one
recipient. When sending email to a distribution group or list set up in an email client such as
Apple Mail or Outlook, a separate email is sent for each recipient in the group.
A security best practice is to generate SMTP credentials for a new user instead of your
Console user that already has permissions assigned to it. For detailed instructions on creating
a user, see Adding Users. The new user must be assigned to a group with permissions to
manage approved-senders and suppressions. For example:
Allow group <group name> to use approved-senders in compartment <compartment name>
Tip
Approved senders should not be created in the root compartment. If approved senders exist in
the root compartment, you are required to create a policy to manage approved senders in the
entire tenant. Creating approved senders in a compartment other than the root allows the
policy to be specific to that compartment.
Tip
l CreateSender
l GetSender
l ListSenders
l DeleteSender
Configure SPF
The Approved Senders section within the Console provides validation of an SPF record for
each of your approved senders. SPF is required for subdomains of oraclegovcloud.com and
recommended in other cases.
1. Open the navigation menu. Under Solutions and Platform, go to Email Delivery and
click Email Approved Senders.
2. Select the checkbox for the approved sender you want to view SPF details for and click
View SPF.
Tip
3. The Manage SPF dialog box appears indicating whether an SPF record for the approved
sender exists.
l If your domain does not currently have an SPF record, the information necessary
to add an SPF record in your DNS setup is displayed. See Managing DNS Service
Zones for instructions on adding a zone record in Oracle Cloud Infrastructure. If
your DNS setup resides with another provider, please reference their
documentation for adding a TXT record to your domain.
o In your DNS setup, create a TXT record and paste the following information
into the record based on the sending location:
l If your domain currently has an SPF DNS record, you must update your record in
order to successfully use Email Delivery.
The following is an example of a command used to view an SPF record:
l If you're using other email providers in addition to Email Delivery, you'll need to
combine the include statements from your other providers with Email Delivery.
To access SMTP sending information to configure the connection in your system, open the
navigation menu. Under Solutions and Platform, go to Email Delivery and click Email
Configuration. The following information is displayed:
l Manage SMTP Credentials: Access your user credentials. Use the SMTP user
credentials (in plain text) when validating your connection.
l Server Name: The Email Delivery service hostname.
l Port: Email Delivery supports TLS on port 25 or 587.
l Use Transport Layer Security (TLS): This field indicates if TLS, the standard means
of performing encryption in transit for email, is being used. Customers must encrypt
email while it is in transit to the Oracle Cloud Infrastructure Email Delivery service.
Encrypted emails are protected from being read during transit.
Important
SMTP Connection Endpoints
Use the following regional endpoints for establishing SMTP connections for sending.
l YNY: smtp.email.ap-chuncheon-1.oci.oraclecloud.com
l HYD: smtp.email.ap-hyderabad-1.oci.oraclecloud.com
l MEL: smtp.email.ap-melbourne-1.oci.oraclecloud.com
l BOM: smtp.email.ap-mumbai-1.oci.oraclecloud.com
l KIX: smtp.email.ap-osaka-1.oci.oraclecloud.com
l ICN: smtp.email.ap-seoul-1.oci.oraclecloud.com
l SYD: smtp.email.ap-sydney-1.oci.oraclecloud.com
l NRT: smtp.email.ap-tokyo-1.oci.oraclecloud.com
l YUL: smtp.email.ca-montreal-1.oci.oraclecloud.com
l YYZ: smtp.email.ca-toronto-1.oci.oraclecloud.com
l AMS: smtp.email.eu-amsterdam-1.oci.oraclecloud.com
l FRA: smtp.email.eu-frankfurt-1.oci.oraclecloud.com
l ZRH: smtp.email.eu-zurich-1.oci.oraclecloud.com
l JED: smtp.email.me-jeddah-1.oci.oraclecloud.com
l GRU: smtp.email.sa-saopaulo-1.oci.oraclecloud.com
l LHR: smtp.email.uk-london-1.oci.oraclecloud.com
l IAD: smtp.us-ashburn-1.oraclecloud.com
l PHX: smtp.us-phoenix-1.oraclecloud.com
TLS Requirements
Oracle maintains strict security policies and only accepts email traffic using Transport Layer
Security (TLS). Use of TLS 1.2 is mandatory to send email using Oracle Cloud Infrastructure.
l TLS_DHE_RSA_WITH_AES_256_CBC_SHA
l TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
l TLS_DHE_DSS_WITH_AES_256_CBC_SHA256
l TLS_RSA_WITH_AES_256_CBC_SHA
l TLS_RSA_WITH_AES_256_CBC_SHA256
l TLS_DHE_RSA_WITH_AES_128_CBC_SHA
l TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
l TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
l TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
l TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
l TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
l TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
Users are required to have correct permissions to manage the suppression list. Currently,
identity policies for suppression must be at the tenant level (not at the compartment level).
The following is an example of the permission policy statement.
Allow group <group name> to manage suppressions in tenancy
Suppressions are stored at the tenancy level. Therefore any request requiring a
compartmentId must provide the tenancyId as the compartmentId. For example:
Allow group <ordinary users> to inspect approved-senders in tenancy
Allow group <power users> to read approved-senders in tenancy
Allow group <sender admins> to manage approved-senders in tenancy
Allow user <mail user> to use approved-senders in tenancy where target.approved-sender.senderId =
<senderId>
Tip
3. In the confirmation dialog box, click OK. The email address is removed from the
Suppression List.
l CreateSuppression
l GetSuppression
l ListSuppressions
l DeleteSuppression
This topic describes the metrics emitted by the metric namespace oci_emaildelivery (the
Email Delivery service).
Note
Prerequisites
l IAM policies: To monitor resources, 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. The policy must give you access to the monitoring
services as well as the resources being monitored. 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 more information on user authorizations for monitoring, see the
Authentication and Authorization section for the related service: Monitoring or
Notifications.
RESOURCEID
For more information about monitoring metrics and using alarms, see Monitoring Overview.
For information about notifications for alarms, see Notifications Overview.
Before you use APEX_MAIL you must configure Oracle Cloud Infrastructure Email Delivery in
your Application Express instance.
1. Identify the SMTP connection endpoint for Email Delivery. You configure the endpoint as
the SMTP Host in your Application Express instance in Step 4. See Configure SMTP
Connection for more information.
2. Generate SMTP credentials for Email Delivery. Your Application Express instance uses
credentials to authenticate with Email Delivery servers when you send email. See
Generate SMTP Credentials for a User for more information.
3. Create an approved sender for Email Delivery. You need to complete this step for all
email addresses you use as the "From" with APEX_MAIL.SEND calls, as the Application
Email From Address in your apps, or in the SMTP_FROM instance parameter. See
Managing Approved Senders for more information.
4. Connect to your Autonomous Transaction Processing as ADMIN user using a SQL client
and configure the following SMTP parameters using APEX_INSTANCE_ADMIN.SET_
PARAMETER:
5. Send a test email using APEX SQL Workshop, SQL Commands specifying one of the
approved senders from Step 3 as "From". For example:
BEGIN
APEX_MAIL.SEND(p_from => '[email protected]',
p_to => '[email protected]',
p_subj => 'Email from Oracle Autonomous Database',
p_body => 'Sent using APEX_MAIL');
END;
/
More Information
l Creating Applications with Oracle Application Express in Autonomous Database
l APEX_MAIL in Oracle Application Express API Reference
l APEX_INSTANCE_ADMIN in Oracle Application Express API Reference
Note
1. Make sure Email Delivery is configured to send email. See Getting Started with Email
Delivery.
Note
smtp_tls_security_level = may
smtp_sasl_auth_enable = yes
smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
smtp_sasl_security_options =
4. Update relayhost to include your SMTP connection endpoint and port. For example:
relayhost = smtp.us-ashburn-1.oraclecloud.com:587
where:
l server is your relay host and port is 25 or 587.
l user is the user name and pass is the password you received when you generated
your SMTP credentials.
7. Enter the permissions in the password file.
Run the following command:
sudo chown root:root /etc/postfix/sasl_passwd && sudo chmod 600 /etc/postfix/sasl_passwd
9. Reload Postfix.
Run the following command:
sudo postfix reload
If you want to monitor the log while you send the test email, open a separate Terminal
window and run the following command before running the test command:
log stream --predicate '(process == "smtpd") || (process == "smtp")' --info
A status=sent (250 Ok) message in the log indicates the email was sent successfully.
Note
More Information
l See the Postfix website for more information on Postfix configuration.
l See TLS errors when integrating with Postfix for troubleshooting techniques related to
Email Delivery.
Note
1. Make sure Email Delivery is configured to send email. See Getting Started with Email
Delivery.
Note
2. In Oracle Enterprise Manager, go to the Setup menu and click Initial Setup Console.
3. In the Initial Setup Console section, click Configure Mail Servers in the navigation
pane.
4. In the Sender Identify section, click Edit.
5. Enter the name of the administrator or system that should send the email notifications
and the email address from which the notifications should be sent, and then click OK.
6. In the Outgoing Mail (SMTP) Servers section, click Create.
7. Enter the mail server host name, the mail server credentials, and the encryption
method to be used, and then click OK.
8. Select the outgoing mail server you wish to test and select Test Mail Server. Note the
confirmation message in the console and verify that you received the test email in your
inbox.
Note
Note
1. Make sure Email Delivery is configured to send email. See Getting Started with Email
Delivery.
Note
set nss-config-dir=/etc/pki/nssdb/
set smtp-use-starttls
set smtp-auth=plain
set smtp=<SMTP connection endpoint>:25
set from=<from_email_address>
set smtp-auth-user=<OCID from smtp credentials>
set smtp-auth-password=<password from smtp credentials>
More Information
l For network security services, see the Mailx documentation.
Note
Assumptions
The following procedures assume the following:
l The following example supplies options to Swaks via the command line in long form, for
example, --server as opposed to the short form, -s.
l The following example assumes the default behavior to connect through network
sockets.
l A local certificate is not required for a TLS connection to be negotiated. The following
example assumes the default behavior where Swaks does not attempt certificate
verification.
l Swaks is primarily intended for use on UNIX-like operating systems with functionality
based on known standards so it should work on most modern mail servers.
1. Ensure Email Delivery is configured to send email. See Getting Started with Email
Delivery.
Note
2. Ensure Swaks is installed. The installation process differs depending on which operating
system you are using. For example, run the following command to install Swaks on
Oracle Linux:
sudo yum install swaks -y
For example:
swaks --pipeline -tls --server smtp.us-ashburn-1.oraclecloud.com --port 25 --auth-user
'ocid1.user.oc1..<unique_ID>' --auth-pass '<password>' --from '[email protected]' --to
'[email protected]' --data 'From: [email protected]\nDate: Thu, 13 Sep 2019\nSubject: Test
Send\n\nTest email'
More Information
l See the Swaks documentation for more information.
Important
1. Ensure Email Delivery is configured to send email. See Getting Started with Email
Delivery.
Note
// Replace smtp_username with your Oracle Cloud Infrastructure SMTP username generated in
console.
static final String SMTP_USERNAME = "<username OCID from SMTP credentials>";
// Replace smtp_password with your Oracle Cloud Infrastructure SMTP password generated in
console.
static final String SMTP_PASSWORD = "<SMTP password>";
// The port you will connect to on the SMTP endpoint. Port 25 or 587 is allowed.
static final int PORT = 587;
System.getProperty("line.separator"),
"<h1>OCI Email Delivery test</h1>",
"<p>This email was sent with OCI Email Delivery using the ",
"<a href='Javamail'>https://github.com/javaee/javamail'>Javamail Package</a>",
" for <a href='Javahttps://www.java.com'>Java</a>."
);
// Create a Session object to represent a mail session with the specified properties.
Session session = Session.getDefaultInstance(props);
// Create a transport.
Transport transport = session.getTransport();
try
{
// Send email.
transport.sendMessage(msg, msg.getAllRecipients());
System.out.println("Email sent!");
finally
9. In the OCIemail.java file, replace the following with your own values:
Note
l FROM - Replace with your sender email address. This email address must be
added to the Approved Senders list in Email Delivery first.
l TO - Replace with your recipient email address.
More Information
l See the JavaMail documentation for more information.
Note
1. Make sure Email Delivery is configured to send email. See Getting Started with Email
Delivery.
Note
sudo vi /etc/mail/authinfo
Note
5. Add support for relaying to the Oracle Cloud Infrastructure Email Delivery SMTP
endpoint.
Run the following command:
sudo sh -c 'echo "Connect:<SMTP connection endpoint> RELAY" >> /etc/mail/access'
6. Regenerate /etc/mail/access.db.
Run the following command:
sudo sh -c 'makemap hash /etc/mail/access.db < /etc/mail/access'
Note
Note
More Information
l For more information, see the Sendmail Installation and Operation Guide.
Note
1. Make sure Email Delivery is configured to send email. See Getting Started with Email
Delivery.
Note
2. Open a Chrome browser and navigate to the SMTP connection endpoint (for example,
https://smtp.us-phoenix-1.oraclecloud.com).
a. Click the certificate, and then click the Certification Path tab.
b. Select the DigiCert root certificate.
Note
6. Update the SMTP settings on the PeopleSoft Application server. For more information,
see SMTP Settings in the PeopleSoft documentation.
Establish an ssh connection to the PeopleSoft Application server machine (as username
"opc") and do the following:
a. Switch user to psadm2 (for example, sudo su - psadm2).
Note
SMTPSSLPort=587
SMTPTLSEnable=true
SMTPTLSRequired=true
Note
7. Add the primary email address for the PeopleSoft application user who is trying to send
notification from within the application. In this example, the user is "PS".
Log in as "PS" and do the following:
a. Open the navigation menu on the PeopleSoft dashboard. Go to PeopleTools,
and then select Security.
b. Select User Profiles, and then click user Profiles. Find the profile for "PS".
c. On the General tab, click Edit Email Addresses.
d. Enter the approved sender email address as the primary email address.
8. Log out of the PeopleSoft application.
9. Reboot the application server using the PSADMIN utility. See Using the Application
Server Administration Menu.
10. Test the email notification delivery.
Log into the PIA as "PS", and select Notify anywhere in the console. For example, you
can do the following:
a. Go to Peopletools, and then select Web Profile.
b. Select Web Profile Configuration.
c. Click Search, and then click PROD in the search results.
d. Click Notify, enter the notification details, and then click OK.
1. You can add the following parameter to help with SMTP debugging: SMTPTrace=1
LogFence should be set to 5 to use this parameter. The system writes the log
information to SMTP<DDMM>.log in %PS_SERVDIR%/LOGS by default, or the custom value
set for Log Directory.
For example:
$PS_CFG_HOME\APPSERV\domain\LOGS\SMTP6_27.log
2. After you set this parameter, you will need to reboot the Application server. Once this
parameter is set, you can monitor the SMTP log.
3. Type ls and find the SMTP file for the date you sent the email.
4. Run the following command:
tail -f <smtp log file and date>
For example,
tail -f SMTP9_17.log
More Information
l SMTP Settings (PeopleSoft)
l Encrypting Passwords in the PeopleSoft Pure Internet Architecture
l My Oracle Support: Is There a Way to Both Authenticate And Secure Emails From
PeopleSoft?
Note
1. Ensure Email Delivery is configured to send email. See Getting Started with Email
Delivery.
Note
2. Ensure Python is installed. The installation process differs depending on which operating
system you are using. For example, run the following command to install Python on
Oracle Linux:
sudo yum install python3 -y
3. In a file editor such as vi, create a python script to test Email Delivery.
Run the following command:
sudo vi ociemail.py
4. In the ociemail.py file, replace the variables with your own values.
For example:
------------------------------------------------------------------------------------------------
#python script for sending SMTP configuration with Oracle Cloud Infrastructure Email Delivery
import smtplib
import email.utils
from email.mime.multipart import MIMEMultipart
from email.mime.text import MIMEText
# Replace the USERNAME_SMTP value with your Email Delivery SMTP username.
USERNAME_SMTP = 'ocid1.user.oc1..<unique_ID>@ocid1.tenancy.oc1..<unique_ID>.vf.com'
# Replace the PASSWORD_SMTP value with your Email Delivery SMTP password.
PASSWORD_SMTP = '<password>'
# If you're using Email Delivery in a different region, replace the HOST value with an SMTP
endpoint. Use port 25 or 587 to connect to the SMTP endpoint.
HOST = "smtp.us-ashburn-1.oraclecloud.com"
PORT = 587
5. To send a test email with Python, run the following command from the directory the
More Information
l More Python script examples can be found on GitHub.
Using this setting, the Postfix SMTP server announces STARTTLS support to remote
SMTP clients, but does not require that clients use TLS encryption.
l If you want to enforce the use of TLS, so that the Postfix SMTP server announces
STARTTLS and accepts no mail without TLS encryption, use the following setting:
smtp_tls_security_level = encrypt
Connectivity Issues
Note
experiencing a network connectivity issue. If you are able to connect to an external MTA, the
network connectivity issue is within Oracle Cloud Infrastructure.
3. Use the following command to test connectivity to the endpoint port 25 or 587
against Google's MX servers.
telnet <IP address> <port>
If you are unable to connect to Google's MX servers, this confirms that you are
having issues connecting to mail servers (port 25 or 587). It is possible that your
egress rules are filtering traffic at the VCN.
If you can connect to an external MTA (that is, you are able to communicate with
a public SMTP endpoint on the correct ports) but you cannot connect to Email
Delivery public SMTP endpoints on those ports, create a service request with My
Oracle Support with this information.
API Errors
For a complete list of common errors returned by all the services for Oracle Cloud
Infrastructure, see API Errors.
The following table lists the common errors returned by the Email Delivery SMTP service.
451 Server error An unexpected error has occurred during the SMTP
conversation.
452 System storage The server is unable to persist the message in its
error delivery queue.
455 Maximum messages The SMTP send burst rate (of messages accepted per
sent per minute minute period) has been exceeded.
reached : limit is
<limit>
455 Maximum messages The SMTP daily send rate (of messages accepted per
sent per day 24 hour period) has been exceeded.
reached : limit is
<limit>
501 Invalid command The base64 encoded AUTH (PLAIN) secret is invalid.
argument, not a
valid Base64
string
501 Invalid command The base64 encoded AUTH (PLAIN) secret does not
argument, does not contain NUL field separator(s).
contain NUL
501 Invalid command The base64 encoded AUTH (PLAIN) secret does not
argument, does not contain NUL field separator(s).
contain the second
NUL
504 AUTH mechanism The client has sent an invalid AUTH command to our
mismatch service.
523 Exceeds byte limit The message has exceeded the size limit enforced by
the service (see server response to EHLO for size
restriction).
535 Authentication The client has sent commands that require SMTP
required authentication succeeded before the service is able
to process (that is, commands are being sent out of
order).
553 <address> Invalid The RFC-822 Internet Address sent by the client is
email address invalid.
l Single opt-in (unconfirmed): A user provides their email address and gives
permission to receive relevant messages. Once the address is provided, messages can
be sent without confirming the email address belongs to the user who provided it.
l Double opt-in (confirmed): A user provides their email address, but before the first
mailing, a confirmation email is sent to the account owner. The email requires action
from the account owner to confirm that future messages are wanted. An account can be
verified by having the owner click a link for reply to the email. The confirmation email
ensures that the address was not added to a third-party mailing list without consent.
l Eliminate duplicate addresses before sending. If addresses that do not exist are mailed
to multiple times, your hard bounce rate could be inflated.
l Ensure that a previous suppression list (possibly from another email service provider)
was not accidentally included.
l Verify that subscribers have opted-in. Do not send to an old list that you found.
l Restrict users from uploading their email client’s contact list in a “select all” fashion.
Forcing users to select addresses individually prevents users from accidentally including
potentially out of date or expired addresses.
with CASL. This article does not constitute legal advice, nor is it intended supplement or
otherwise affect your rights or obligations under your service agreement with Oracle,
including your obligations under Oracle’s Acceptable Use Policy. If you have questions about
CASL or the legality of your sending practices, we encourage you to speak with an attorney
who specializes in that subject matter.
CASL and its related regulations apply to any “commercial electronic message” sent from or
to Canadian computers and devices in Canada. Electronic messages that are merely routed
through Canadian computer systems are not subject to CASL.
Are there any types of messages that are exempt from CASL?
These types of electronic messages are exempt from CASL for various reasons.
l Messages that provide warranty, recall, safety, or security information about a product
or service purchased by the recipient.
l Messages that provide information about a purchase, subscription, membership,
account, loan, or other ongoing relationship, including delivery of product updates or
upgrades.
l A single message to a recipient without an existing relationship based on a referral. The
full name of the referring person must be disclosed in the message. The referrer might
be family or have another relationship with the person to whom you are sending.
If your message does not meet one of these criteria, consent is required under CASL. Not all
of the previous messages listed are permitted under the Oracle Cloud Hosting and Delivery
Policy.
Under CASL, “express consent” means a written or oral agreement to receive specific types of
messages. For example, “You want to receive monthly newsletters and weekly discount
notifications from Oracle”.
Express consent is only valid if your request for consent clearly and simply describes the
following information:
The requestor can be you or someone for whom you are asking. If you are requesting consent
on behalf of a client, the name and contact information of the client must be included with the
consent request.
Under CASL, you can only obtain implied consent when certain circumstances exist, including
when:
l A recipient has purchased a product, service or made another business deal, contract,
or membership with your organization in the last 24 months.
l You are a registered charity or political organization, and the recipient has made a
donation or gift, has volunteered, or attended a meeting organized by you.
l A professional message is sent to someone whose email address was given to you, or is
conspicuously published, and who has not published or told you that unsolicited
messages are not wanted.
After July 1, 2017, you can only send to recipients with express consent or whose implied
consent is valid under CASL.
The full text of the law can be found on the website for the Canadian Justice Department. The
Canadian Radio and Telecommunications Commission has also set up an FAQ page and some
guidelines for obtaining consent. If you have any questions, we encourage you to contact an
attorney who is familiar with the law.
Often, the Oracle Cloud Hosting and Delivery Policy is more stringent than CASL
requirements. It is important that you review Oracle policies before using the service.
If you are unable to resolve the issue, you can go to My Oracle Support and create a service
request. See Creating a Service Request for more information.
Overview of Events
Oracle Cloud Infrastructure Events enables you to create automation based on the state
changes of resources throughout your tenancy. Use Events to allow your development teams
to automatically respond when a resource changes its state.
Note
Services emit events for resources or data. For example, Object Storage emits events for
buckets and objects. Services emit different types of events for resources, which are
distinguished as event types. Buckets and objects have event types of create, update, and
delete, for example. Event types are the changes that produce events by a given resource.
For a list of services that produce events and the event types that those services track, see
Services that Produce Events.
You work with events by creating rules. Rules include a filter you define to specify events
produced by the resources in your tenancy. The filter is flexible:
l You can define filters that match only certain events or all events.
l You can define filters based on the way resources are tagged or the presence of specific
values in attributes from the event itself.
Rules must also specify an action to trigger when the filter finds a matching event. Actions are
responses you define for event matches. You set up select Oracle Cloud Infrastructure
services that the Events service has established as actions (more on these select services
follows). The resources for these services act as destinations for matching events. When the
filter in the rule finds a match, the Events service delivers the matching event to one or more
of the destinations you identified in the rule. The destination service that receives the event
then processes the event in whatever manner you defined. This delivery provides the
automation in your environment.
You can only deliver events to certain Oracle Cloud Infrastructure services with a rule. Use
the following services to create actions:
l Notifications
l Streaming
l Functions
Events Concepts
The following concepts are essential to working with Events.
EVENTS
An automatic notification of a state change as reported by an event-emitting Oracle Cloud
Infrastructure resource. For example, an database resource emits a backup.begin event
when a backup begins.
EVENT TYPES
A distinction between the different types of events. For more information, see Services
that Produce Events.
RULES
A JSON object you create to subscribe to an event type and trigger an action should that
event occur. For example, a rule might specify that backup.end event types from
databases trigger the Notifications service to send an email to a particular DevOps
engineer. For more information, see Matching Events with Filters.
ACTIONS
Rules must also specify an action to trigger when the filter finds a matching event. Actions
are responses you define for event matches. You set up select Oracle Cloud Infrastructure
services that the Events service has established as actions. The resources for these
services act as destinations for matching events. When the filter in the rule finds a match,
the Events service delivers the matching event to one or more of the destinations you
identified in the rule. The destination service that receives the event then processes the
event in whatever manner you defined. This delivery provides the automation in your
environment.
You can only deliver events to certain Oracle Cloud Infrastructure services with a rule.
Use the following services to create actions:
l Notifications
l Streaming
l Functions
Region Availability
Events is currently available in all regions of the commercial realm. Events is currently not
available in regions within the Government Cloud realm.
An administrator in your organization needs to set up groups, compartments, and policies that
control which users can access which services, which resources, and the type of access. For
example, the policies control who can create new users, create and manage the cloud
network, launch instances, create buckets, download objects, etc. For more information, see
Getting Started with Policies. For specific details about writing policies for each of the
different services, see Policy Reference.
If you’re a regular user (not an administrator) who needs to use the Oracle Cloud
Infrastructure resources that your company owns, contact your administrator to set up a user
ID for you. The administrator can confirm which compartment or compartments you should be
using.
Administrators: You must write IAM policy that authorize users to work with rules. For more
information, see Events and IAM Policies.
See Service Limits for a list of applicable limits and instructions for requesting a limit
increase. To set compartment-specific limits on a resource or resource family, administrators
can use compartment quotas.
Warning
Important
You can use existing users, groups, and compartments or make new ones.
information.
d. Select the users from the drop-down list, and then click Add.
To create a compartment
If suitable compartment for rules and the resources that emit events doesn't already exist,
log in to the Console as a tenancy administrator and create it.
Before users can start using Events to create automation, as a tenancy administrator you
must create IAM policy:
l Description: A meaningful description. You can change this later if you want to.
Avoid entering confidential information.
l Statement: Enter the following policy statements to give users in the group the
ability to manage and create rules:
This line gives the user inspect access to resources in compartments to select
actions.
allow group <RuleAdmins> to inspect compartments in tenancy
This line gives the user access to defined tags to apply filter tags to rules.
allow group <RuleAdmins> to use tag-namespaces in tenancy
These lines give the user access to Streaming resources for actions
allow group <RuleAdmins> to inspect streams in tenancy
allow group <RuleAdmins> to use stream-push in tenancy
allow group <RuleAdmins> to use stream-pull in tenancy
These lines give the user access to Functions resources for actions.
allow group <RuleAdmins> to use virtual-network-family in tenancy
allow group <RuleAdmins> to manage function-family in tenancy
This line give the user access to Notifications topics for actions.
allow group <RuleAdmins> to use ons-topic in tenancy
This line gives the user manage access to rules for Events.
allow group <RuleAdmins> to manage cloudevents-rules in tenancy
6. Click Create.
If a suitable Notifications topic doesn't already exist, then you must log in to the Console as a
tenancy administrator and create it. Whether you use an existing topic or create a new one,
add an email address as a subscription so that you can monitor that email account for
notifications.
To create a topic
1. Open the navigation menu. Under Solutions and Platform, go to Application
Integration and click Notifications.
2. Click Create Topic at the top of the topic list.
To create a subscription
1. Open the navigation menu. Under Solutions and Platform, go to Application
Integration and click Notifications.
2. Click the name of the topic that you created in the previous step or the topic you intend
to use for this tutorial.
3. On the topic detail page, click Create Subscription.
4. In the Create Subscription dialog box, select Email, and then type an email address.
5. Click Create.
The subscription has been created and a subscription confirmation URL will be sent. The
subscription remains in "Pending" status until it has been confirmed.
To confirm a subscription
l In the confirmation email sent to the address you specified in the previous procedure,
click the confirmation URL.
To create a rule
1. Open the navigation menu. Under the Solutions and Platform group, go to
Application Integration and click Events Service.
2. Choose a Compartment you have permission to work in, and then click Create Rule.
Events compares the rules you create in this compartment to event messages emitted
from resources in this compartment and any child compartments.
3. Enter the following.
l Display Name: Specify a friendly name for the rule. You can change this name
later. Avoid entering confidential information.
l Description: Specify a description of what the rule does. You can change this
description later. Avoid entering confidential information.
4. In Event Matching, select Event Type.
To create a bucket
1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
2. Select the compartment where you created your rule (or any of its subordinate
compartments).
3. Click Create Bucket.
Tip
l To specify the actions for your rule, use a JSON formatted file. You create this file
before you create the rule, and the file simplifies the amount of information you must
type at the command line.
l To specify an event to match, use a JSON formatted string. You type this right into the
console as you create the rule.
"actions": [
{
"actionType": "FAAS",
"description": "string",
"functionId": "<function_OCID>",
"isEnabled": true
},
{
"actionType": "ONS",
"description": "string",
"isEnabled": true,
"topicId": "<topic_OCID>"
},
{
"actionType": "OSS",
"description": "string",
"isEnabled": true,
"streamId": "<stream_OCID>"
}
]
}
To create a rule
Open a command prompt and run oci events rule create to create a rule.
Examples
The following example shows how to pass a simple condition that matches all events.
Everything between the double quotes (" ") is a string, while the brackets { } indicate
JSON:
oci events rule create --display-name <friendly_name> --is-enabled true --condition "{}" --
compartment-id <compartment_OCID> --actions file://action.json --wait-for-state=ACTIVE
To pass complex input to the CLI as a JSON string, you must enclose the entire block in
double quotes. Inside the block, each double quote for the key and value strings must
be escaped with a backslash (\) character.
For example:
oci events rule create --display-name <friendly_name> --is-enabled true --condition "
{\"eventType\":[\"com.oraclecloud.objectstorage.createbucket\"]}" --compartment-id <compartment_
OCID> --actions file://action.json --wait-for-state=ACTIVE
Tip
l compartment-id indicates the compartment where the rule applies. Events evaluates
messages from resources in this compartment and any child compartments.
l actions indicates the location in the local file system of the JSON formatted file you
created to specify the actions for a rule.
l wait-for-state= when used with ACTIVE indicates that the CLI should wait for the
service to create the rule, do another GET operation, and then display the rule in the
active state. Without the option, the CLI displays the rule immediately in the creating
state.
For example:
oci events rule create --display-name CLI-created_rule --is-enabled true --condition "{\"eventType\":
[\"com.oraclecloud.objectstorage.createbucket\"]}" --compartment-id <compartment_OCID> --actions <path_
to_json_formatted_actions_file> --wait-for-state=ACTIVE
Note
When you run the preceding command, the CLI prompts you about the rule and its display:
Action completed. Waiting until the resource has entered state: ACTIVE
{
"data": {
"actions": {
"actions": [
{
"action-type": "ONS",
"description": "Notifications action",
"id": "ocid1.eventaction.oc1.phx.<unique_ID>",
"lifecycle-message": null,
"lifecycle-state": "ACTIVE",
"topic-id": "ocid1.onstopic.oc1.phx.<unique_ID>"
}
]
},
"compartment-id": "ocid1.compartment.oc1..<unique_ID>",
"condition": "{\"eventType\":[\"com.oraclecloud.objectstorage.createbucket\"]}",
"defined-tags": {},
"description": null,
"display-name": "CLI-created_rule",
"freeform-tags": {},
"id": "ocid1.eventrule.oc1.phx.<unique_ID>",
"is-enabled": true,
"lifecycle-message": null,
"lifecycle-state": "ACTIVE",
"time-created": "2019-04-25T01:32:56.855000+00:00"
},
"etag": "<unique_ID>--gzip"
}
To create a bucket
1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
2. Select the compartment where you created your rule (or any of its subordinate
compartments).
3. Click Create Bucket.
4. In the Create Bucket dialog, specify the attributes of the bucket:
l Name: Required. A user-friendly name or description. Avoid entering confidential
information.
l Storage Tier: Select the tier in which you want to store your data. Available tiers
include:
o Standard is the primary default Object Storage tier for storing data that is
accessed frequently and requires fast and immediate access.
o Archive is a special tier for storing data that is accessed infrequently and
requires long retention periods. Access to data in the Archive tier is not
immediate. You must restore archived data before it’s accessible.
5. Click Create Bucket.
Tip
Background
To understand filtering, it's helpful to review the structure of an actual event message. Events
uses JSON objects to represent events. This is an event:
{
"cloudEventsVersion": "0.1",
"eventID": "<unique_ID>",
"eventType": "com.oraclecloud.objectstorage.deletebucket",
"source": "objectstorage",
"eventTypeVersion": "1.0",
"eventTime": "2019-01-10T21:19:24Z",
"contentType": "application/json",
"extensions": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>"
},
"data": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>",
"compartmentName": "example_name",
"resourceName": "my_bucket",
"resourceId": "ocid1.compartment.oc1..<unique_ID>",
"availabilityDomain": "NfHZ:PHX-AD-2",
"freeFormTags": {
"Department": "Finance"
},
"definedTags": {
"Operations": {
"CostCenter": "42"
}
},
"additionalDetails": {
"namespace": "example_namespace",
"publicAccessType": "NoPublicAccess",
"eTag": "f8ffb6e9-f602-460f-a6c0-00b5abfa24c7"
}
}
}
l Events all have the same set of top-level attributes, which are known as the event
envelope. With one exception, most of these top-level attributes are not that useful for
creating filters. The exception is eventType, which identifies the type of event included
in the payload.
l The payload of the event appears within the data attribute. The information in this field
depends on which service produced the event and the event type requested. The
information in the payload is useful for isolating one event from another with a filter.
For more information about the envelope, see Contents of an Event Message. For a list of all
the services that produce events, see Services that Produce Events.
l Fields not mentioned in a filter are ignored. You can create a valid filter that matches all
event messages with two curly brackets.
l For a filter to match an event, the event must contain all the field names listed in the
filter. Field names must appear in the filter with the same nesting structure used in the
event.
l Rules apply to events in the compartment in which you create them and any child
compartments. This means that a filter specified by a rule only matches events emitted
from resources in the same compartment or any child compartments.
l Wildcard matching is supported with the asterisk (*) character. See Examples of
Wildcard Matching in Filters.
When you add fields to the filter, you limit the events that the filter can match. For example,
the following filter matches only deletebucket events.
{
...
"condition": "{
"eventType": "com.oraclecloud.objectstorage.deletebucket"
}"
}
To create a filter for more than one event type, use an array in eventType. The following filter
matches deletebucket and createbucket events.
{
...
"condition": "{
"eventType": [
"com.oraclecloud.objectstorage.deletebucket",
"com.oraclecloud.objectstorage.createbucket"
]
}"
}
The important thing to note is how the field names in the filter match the nesting structure of
the event.
{
...
"condition": "{
"data": {
"compartmentName": "example_name",
"resourceName": "my_bucket"
}
}"
}
{
...
"condition": "{
"data": {
"additionalDetails": {
"publicAccessType": "NoPublicAccess"
}
}
}"
}
Neither of the following filters would match the event at the top of this page. The first because
the filter specifies a PublicAccessType not found in the event. The second because the event
specifies a name for different bucket.
{
...
"condition": "{
"data": {
"compartmentName": "example_name",
"resourceName": "my_bucket",
"additionalDetails": {
"publicAccessType": "PublicAccess"
}
}
}"
}
{
...
"condition": "{
"data": {
"additionalDetails": {
"publicAccessType": "NoPublicAccess"
}
}
}"
}
"condition": "{
"data": {
"resourceName": [
"my_bucket_2",
"my_bucket_1",
"my_bucket"
],
"additionalDetails": {
"namespace": "example_namespace",
"publicAccessType": "NoPublicAccess"
}
}
}"
}
You can use an array in eventType (or any of the top-level fields), the event payload as
shown in the preceding example, or both the event payload and a top-level field.
{
...
"condition": "{
"eventType": [
"com.oraclecloud.objectstorage.deletebucket",
"com.oraclecloud.objectstorage.createbucket"
],
"data": {
"resourceName": [
"my_bucket_2",
"my_bucket_1",
"my_bucket"
],
"additionalDetails": {
"namespace": "example_namespace",
"publicAccessType": "NoPublicAccess"
}
}
}"
}
l Use the wildcard only in attribute values. You cannot use the asterisk for matching in
keys.
l An attribute value with only an asterisk matches all values for the associated attribute
name, but not null.
l The period character has no special meaning in a filter.
You can add the asterisk at the start of a string, in the middle, or at the end. All of the filters
that follow match the event at the top of the page.
l The first matches because the wildcard in displayName matches the bucket naming
pattern.
l The second one matches because the publicAccessType uses a wildcard. Because of
the use of the wildcard, these first two filters would also match events from buckets
with a similar naming pattern and would include events from buckets with or without
public access.
l The third one matches because the event type includes all types of bucket events.
...
"condition": "{
"data": {
"resourceName": "my_bucket*",
"additionalDetails": {
"namespace": "example_namespace",
"publicAccessType": "NoPublicAccess"
}
}
}"
}
{
...
"condition": "{
"data": {
"resourceName": [
"my_bucket_2",
"my_bucket_1",
"my_bucket"
],
"additionalDetails": {
"namespace": "example_namespace",
"publicAccessType": "*"
}
}
}"
}
{
...
"condition": "{
"eventType": "com.oraclecloud.objectstorage.*bucket",
"data": {
"resourceName": [
"my_bucket_2",
"my_bucket_1",
"my_bucket"
],
"additionalDetails": {
"namespace": "example_namespace",
"publicAccessType": "NoPublicAccess"
}
}
}"
}
This line gives the user inspect access to resources in compartments to select actions.
allow group <RuleAdmins> to inspect compartments in tenancy
This line gives the user access to defined tags to apply filter tags to rules.
allow group <RuleAdmins> to use tag-namespaces in tenancy
These lines give the user access to Streaming resources for actions
allow group <RuleAdmins> to inspect streams in tenancy
allow group <RuleAdmins> to use stream-push in tenancy
allow group <RuleAdmins> to use stream-pull in tenancy
These lines give the user access to Functions resources for actions.
allow group <RuleAdmins> to use virtual-network-family in tenancy
allow group <RuleAdmins> to manage function-family in tenancy
This line give the user access to Notifications topics for actions.
allow group <RuleAdmins> to use ons-topic in tenancy
This line gives the user manage access to rules for Events.
allow group <RuleAdmins> to manage cloudevents-rules in tenancy
Warning
Note
Rules apply to events in the compartment in which you create them and any child
compartments. Create a rule in the compartment with the resource you want to monitor
and specify where to deliver matching events. For example, in the ABC compartment,
you might create a rule that filters for Autonomous Data Warehouse backup events.
Since Events has no requirement about the location of action resources, you could
specify a topic in the XYZ compartment as the resource to deliver any matching events.
With Events, you can also use tags to target resources in your tenancy. You target resources
by adding the tag to a filter in a rule. A filter tag helps you hone automation by targeting only
resources that contain a particular tag. For example, let's say you have dozens of Database
instances in your tenancy, but only a few of the most critical of these instances have the tag
"Operations." You could create a rule that triggers a particular action for resources that only
contain the "Operations" tag.
Policy for working with filter tags is no different from policy for working with tags.
Monitoring Rules
You can monitor the health, capacity, and performance of your Oracle Cloud Infrastructure
resources by using metrics, alarms, and notifications. For more information, see Monitoring
Overview and Notifications Overview.
For more information about monitoring the rules you create, see Events Metrics.
To create a rule
1. Open the navigation menu. Under the Solutions and Platform group, go to
Application Integration and click Events Service.
2. Choose a Compartment you have permission to work in, and then click Create Rule.
Events compares the rules you create in this compartment to event messages emitted
from resources in this compartment and any child compartments.
3. Enter the following.
l Display Name: Specify a friendly name for the rule. You can change this name
later. Avoid entering confidential information.
l Description: Specify a description of what the rule does. You can change this
description later. Avoid entering confidential information.
4. In Rule Conditions, create a filter:
To add an attribute
You must first select an event type to add an attribute.
a. Select Attribute.
b. Select an Attribute Name.
c. Enter an Attribute Value. Attribute values are optional.
d. Click + Another Condition and select Attribute to add another attribute.
This filter will match events of the events types with the attributes you specify.
Tip
For more information, see Contents of an Event Message and Matching Events with
Filters.
5. In Actions, specify the actions resources to trigger when the filter finds a match:
To select a topic
a. Select Notifications.
b. Select the Notifications Compartment.
c. Select the Topic.
d. Click + Another Action and select Notifications to add another topic.
To select a stream
a. Select Streaming.
b. Select the Stream Compartment.
c. Select the Stream.
d. Click + Another Action and select Streaming to add another stream.
To select a function
a. Select Functions.
b. Select the Function Compartment.
c. Select a Function Application.
d. Select the Function.
e. Click + Another Action and select Functions to add another function.
To edit a rule
1. Open the navigation menu. Under the Solutions and Platform group, go to
Application Integration and click Events Service.
2. Choose a Compartment that has the rule you want to edit.
3. For the rule you want to edit, click the Actions icon (three dots), and then click Edit.
4. Make your changes and click Save Changes.
To validate a rule
You can only evaluate a rule against one event type at a time. Repeat as necessary to test
different event types.
1. Open the navigation menu. Under the Solutions and Platform group, go to
Application Integration and click Events Service.
2. Choose a Compartment you have permission to work in, and then click the Name of
the rule you want to test.
3. Click Validate Rule.
4. Take one or more of the following actions:
l If there are no event types in the rule, select the service and event type you want
to test.
l If you want to test a different event type than the one selected by default, select
the service and event type you want to test.
l If you added attribute values or filter tags to the rule, edit the example data in the
event to match the values in your rule.
5. Click Check if Example Event Matches Rule.
For more information, see Matching Events with Filters and Contents of an Event Message.
To delete a rule
1. Open the navigation menu. Under the Solutions and Platform group, go to
Application Integration and click Events Service.
2. Choose the Compartment that has rule you want to delete.
3. For the rule you want to delete, click the Actions icon (three dots) , and then click
Delete.
4. Confirm when prompted.
To select a topic
a. Select Notifications.
b. Select the Notifications Compartment.
c. Select the Topic.
To select a stream
a. Select Streaming.
b. Select the Stream Compartment.
c. Select the Stream.
To select a function
a. Select Functions.
b. Select the Function Compartment.
c. Select a Function Application.
To edit an action
1. Open the navigation menu. Under the Solutions and Platform group, go to
Application Integration and click Events Service.
2. Choose a Compartment you have permission to work in, and then click the Name of
the rule you want to update.
3. In the Resources menu, click Actions.
4. Select an action.
5. Go to Actions and click Edit.
The Edit Action box appears.
6. Make your changes and click Save Changes.
To remove an action
1. Open the navigation menu. Under the Solutions and Platform group, go to
Application Integration and click Events Service.
2. Choose a Compartment you have permission to work in, and then click the Name of
the rule you want to update.
3. In the Resources menu, click Actions.
4. Select an action.
5. Go to Actions and click Remove.
6. Confirm when prompted.
Each rule must have one action.
2. Choose a Compartment you have permission to work in, and then click the Name of
the rule you want to update.
3. In the Resources menu, click Event Matching.
4. Select an event type.
5. Click Edit.
The Edit Event Type box appears.
6. Make your changes and click Save Changes.
b. Enter more values for attribute name in the same manner as before.
l To specify the actions for your rule, use a JSON formatted file. You create this file
before you create the rule, and the file simplifies the amount of information you must
type at the command line.
l To specify an event to match, use a JSON formatted string. You type this right into the
console as you create the rule.
For information about using the CLI, see Command Line Interface (CLI). For a complete list of
flags and options available for CLI commands, see CLI Help.
1. Create a file and add the following content. This content doesn't have to be escaped or
on a single line, it just has to contain valid JSON.
{
"actions": [
{
"actionType": "FAAS",
"description": "string",
"functionId": "<function_OCID>",
"isEnabled": true
},
{
"actionType": "ONS",
"description": "string",
"isEnabled": true,
"topicId": "<topic_OCID>"
},
{
"actionType": "OSS",
"description": "string",
"isEnabled": true,
"streamId": "<stream_OCID>"
}
]
}
2. Edit the file and remove any objects you don't want to use as an action. For example, if
you wanted to only use Notifications as an action, then you would delete all the other
objects.
{
"actions": [
{
"actionType": "ONS",
"description": "string",
"isEnabled": true,
"topicId": "<topic_OCID>"
}
]
}
3. Edit the file and fill in any variables with actual values from your tenancy, as shown in
the following example.
{
"actions": [
{
"actionType": "ONS",
"description": "string",
"isEnabled": true,
"topicId": "<topic_OCID>"
}
]
}
4. Add a description.
5. Save the file as action.json
6. To create a rule and specify Notifications as an action, run the following command.
oci events rule create --display-name <friendly_name> --is-enabled true --condition "{}" --
compartment-id <compartment_OCID> --actions file://action.json
To create a rule
Open a command prompt and run oci events rule create to create a rule.
Examples
The following example shows how to pass a simple condition that matches all events.
Everything between the double quotes (" ") is a string, while the brackets { } indicate
JSON:
oci events rule create --display-name <friendly_name> --is-enabled true --condition "{}" --
compartment-id <compartment_OCID> --actions file://action.json --wait-for-state=ACTIVE
To pass complex input to the CLI as a JSON string, you must enclose the entire block in
double quotes. Inside the block, each double quote for the key and value strings must
be escaped with a backslash (\) character.
For example:
oci events rule create --display-name <friendly_name> --is-enabled true --condition "
{\"eventType\":[\"com.oraclecloud.objectstorage.createobject\"]}" --compartment-id <compartment_
OCID> --actions file://action.json --wait-for-state=ACTIVE
Tip
For example:
oci events rule create --display-name <friendly_name> --is-enabled true --condition <json_formatted_
string> --compartment-id <compartment_OCID> --actions <json_formatted_file> --wait-for-state=ACTIVE
Note
To delete a rule
Open a command prompt and run oci events rule delete to delete a single rule. For
example:
oci events rule delete --rule-id <rule_OCID>
The command returns a prompt, asking for confirmation. Type y to delete the rule.
Open a command prompt and run oci events rule get to get information about a single
rule. For example:
oci events rule get --rule-id <rule_OCID>
"lifecycle-state": "ACTIVE",
"topic-id": "ocid1.onstopic.oc1.phx.<unique_ID>"
}
]
},
"compartment-id": "ocid1.compartment.oc1..<unique_ID>",
"condition": "{\n \"eventType\": [\n
\"com.oraclecloud.databaseservice.autonomous.datawarehouse.backup.end\",\n \"CustomEventType\"\n
]\n}",
"defined-tags": null,
"description": null,
"display-name": "rule_name",
"freeform-tags": null,
"id": "ocid1.eventrule.oc1.phx.<unique_ID>",
"is-enabled": true,
"lifecycle-message": null,
"lifecycle-state": "ACTIVE",
"time-created": "2019-01-23T00:48:20.155000+00:00"
},
"etag": "<unique_ID>--gzip"
}
"time-created": "2019-01-22T20:10:53.562000+00:00"
},
{
"compartment-id": "ocid1.compartment.oc1..<unique_ID>",
"condition": "{}",
"description": null,
"display-name": "rule_2",
"id": "ocid1.eventrule.oc1.phx.<unique_ID>",
"is-enabled": true,
"lifecycle-state": "ACTIVE",
"time-created": "2019-01-22T20:27:25.099000+00:00"
},
...
{
"compartment-id": "ocid1.compartment.oc1..<unique_ID>",
"condition": "{\"eventType\":[\"com.oraclecloud.objectstorage.createobject\"]}",
"description": null,
"display-name": "rule_75",
"id": "ocid1.eventrule.oc1.phx.<unique_ID>",
"is-enabled": true,
"lifecycle-state": "ACTIVE",
"time-created": "2019-01-22T23:08:12.379000+00:00"
}
]
}
To update a rule
Open a command prompt and run oci events rule update to update a rule.
For example:
oci events rule update --rule-id ocid1.eventrule.oc1.phx.<unique_ID> --condition "{}" --wait-for-
state=ACTIVE
The previous command would update the condition of the rule to use an empty JSON string.
The CLI updates the rule, waits for the rule to update and change to the active state (only if
you used the --wait-for-state option), then displays the updated rule.
l description
l is-enabled
l condition
l actions
l freeform-tags
l defined-tags
l ChangeRuleCompartment
l CreateRule
l DeleteRule
l GetRule
l UpdateRule
l ListRules
Event Envelope
These attributes for an event envelope are the same for all events. The structure of the
envelope follows the CloudEvents industry standard format hosted by the Cloud Native
Computing Foundation ( CNCF).
Property Description
Note
data The payload of the event. All of the information within data comes
from the resource emitting the event. See the following table for
more detail on the structure of the payload.
eventID The UUID of the event. This identifier is not an OCID, but just a
unique ID for the event.
eventTime The time of the event, expressed in RFC 3339 timestamp format.
Property Description
eventType The type of event that happened. For a list of all services that
produce events and the even types that those services track, see
Services that Produce Events.
Note
extensions The OCID of the compartment from which the event originates. If
the event originates from the root compartment of the tenancy,
then this attribute specifies a tenancy OCID. This attribute is
mandatory in the Oracle Cloud Infrastructure implementation of the
CloudEvents specification.
source The resource that produced the event. For example, an Autonomous
Database or an Object Storage bucket.
Payload
The data in these fields depends on which service produced the event and the event type it
defines.
Property Description
compartmentId The OCID of the compartment of the resource emitting the event.
compartmentName The name of the compartment of the resource emitting the event.
additionalDetails A container for attributes unique to the resource emitting the event.
In the example bucket event that follows, the payload includes
three Object Storage attributes:
l namespace
l publicAccessType
l eTag
Resource Identifiers
Most types of Oracle Cloud Infrastructure resources have a unique, Oracle-assigned identifier
called an Oracle Cloud ID (OCID). For information about the OCID format and other ways to
identify your resources, see Resource Identifiers.
An Example Event
The following is an example bucket event emitted by Object Storage.
{
"cloudEventsVersion": "0.1",
"eventID": "<unique_ID>",
"eventType": "com.oraclecloud.objectstorage.deletebucket",
"source": "objectstorage",
"eventTypeVersion": "1.0",
"eventTime": "2019-01-10T21:19:24Z",
"contentType": "application/json",
"extensions": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>"
},
"data": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>",
"compartmentName": "example_name",
"resourceName": "my_bucket",
"resourceId": "ocid1.compartment.oc1..<unique_ID>",
"availabilityDomain": "NfHZ:PHX-AD-2",
"freeFormTags": {
"Department": "Finance"
},
"definedTags": {
"Operations": {
"CostCenter": "42"
}
},
"additionalDetails": {
"namespace": "example_namespace",
"publicAccessType": "NoPublicAccess",
"eTag": "f8ffb6e9-f602-460f-a6c0-00b5abfa24c7"
}
}
}
l Analytics Cloud
l API Gateway
l Application Migration
l Big Data
l Block Volume
l Budgets
l Compute
l Container Engine for Kubernetes
l Database
l Data Safe
l Data Science
l Data Transfer
l Digital Assistant
l File Storage
l Functions
l Health Checks
l IAM
l Integration
l Networking
l NoSQL Database Cloud
l Notifications
l Object Storage
l OS Management
l Resource Manager
l WAF
In this section:
Analytics Cloud
For details about events emitted by Analytics Cloud, see Service Events.
API Gateway
API Gateway resources that emit events:
End
API Deployment Example
Gateway Example
}
}
Application Migration
For details about events emitted by Application Migration, see Service Events.
Big Data
For details about events emitted by Big Data, see Service Events.
Block Volume
Block Volume resources that emit events:
These are the event types that block volume backups emit:
Compartment
"source": "BlockVolumes",
"eventTime": "2019-01-10T21:19:24Z",
"contentType": "application/json",
"data": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>",
"compartmentName": "example_name",
"resourceName": "my_volumebackup via policy:gold",
"resourceId": "ocid1.volumebackup.oc1..<unique_ID>",
"additionalDetails": {
"sourceType": "SCHEDULED",
"volumeId": ""ocid1.volume.oc1..<unique_ID>"
}
}
"eventID": "<unique_ID>",
"extensions": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>"
}
}
Compartment End
Begin
Begin
End
These are the event types that boot volume backups emit:
Begin
Begin
"volumeId": ""ocid1.volume.oc1..<unique_ID>"
}
}
"eventID": "<unique_ID>",
"extensions": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>"
}
}
These are the event types that volume groups and volume group backups emit:
Compartment
Begin
End
Begin
End
Budgets
Budgets resources that emit events:
l Alert Rule
l Budget
l Create Triggered Alert
"additionalDetails": {
"budgetId": "ocid1.budget.oc1.phx.<unique_ID>",
"targetType": "COMPARTMENT"
}
},
"extensions": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>"
}
}
Budget Example
"additionalDetails": {
"targetCompartmentId": "ocid1.tenancy.oc1..<unique_ID>",
"targetType": "COMPARTMENT"
}
},
"extensions": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>"
}
}
This is the event type that the create triggered alert emits:
"extensions": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>"
}
}
Compute
Compute resources that emit events:
These are the event types that autoscaling configurations and autoscaling policies emit:
Configuration
Configuration
Configuration
Autoscaling Example
Begin
End
"compartmentId": "ocid1.compartment.oc1..<unique_ID>"
}
}
Create cluster network end and terminate cluster network end don't include the availability
domain.
"compartmentId": "ocid1.compartment.oc1..<unique_ID>"
}
Image Example
"compartmentName": "example_compartment",
"resourceName": "my_image",
"resourceId": "ocid1.image.oc1.iad.<unique_ID>",
"availabilityDomain": "SoSC:PHX-AD-3"
},
"eventID": "<unique_ID>",
"extensions": {
"compartmentId": "ocid1.tenancy.oc1..<unique_ID>"
}
}
Change image compartment doesn't include the resource name or availability domain.
These are the event types that Compute instances and instance attachments emit:
This is a reference event for most instance events (attach/detach volume and boot volume
events don't include additional details):
{
"eventType": "com.oraclecloud.computeapi.launchinstance.begin",
"cloudEventsVersion": "0.1",
"eventTypeVersion": "2.0",
"source": "ComputeApi",
"eventTime": "2019-08-15T21:21:48.586Z",
"contentType": "application/json",
"data": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>",
"compartmentName": "example_compartment",
"resourceName": "my_instance",
"resourceId": "ocid1.instance.oc1.phx.<unique_ID>",
"availabilityDomain": "SoSC:PHX-AD-3",
"additionalDetails": {
"imageId": "ocid1.image.oc1.phx.<unique_ID>",
"shape": "VM.Standard2.1",
"type": "CustomerVmi"
}
},
"eventID": "<unique_ID>",
"extensions": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>"
}
}
"eventTypeVersion": "2.0",
"source": "ComputeApi",
"eventTime": "2019-08-16T12:07:14.623Z",
"contentType": "application/json",
"data": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>",
"compartmentName": "example_compartment",
"resourceName": "my_instance",
"resourceId": "ocid1.instance.oc1.phx.<unique_ID>",
"availabilityDomain": "SoSC:PHX-AD-3",
"additionalDetails": {
"imageId": "ocid1.image.oc1.phx.<unique_ID>",
"instanceActionType": "start",
"shape": "VM.Standard2.1",
"type": "CustomerVmi"
}
},
"eventID": "<unique_ID>",
"extensions": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>"
}
}
These are the event types that Compute instance configurations emit:
Configuration
Configuration
Configuration Begin
Configuration End
Configuration
These are the event types that Compute instance console connections emit:
Connection End
Connection End
}
}
These are the event types that Compute instance pools emit:
These instance pool events don't include the availability domain: create instance pool end,
detach load balancer end, reset instance pool end, soft reset instance pool end, start instance
pool end, stop instance pool end, terminate instance pool end, and update instance pool end.
Cluster Example
}
}
Database
Database resources that emit events:
End
Automatic Stop
Reminder (emitted 48
hours prior to database
stop)
Automatically Stopped
Automatically
Terminated
"dataStorageSizeInTBs": 1,
"timeCreated": "2019-07-10T14:06:10.905Z",
"timeUpdated": "2019-07-10T14:06:10.905Z",
"serviceConsoleUrl": null,
"licenseType": null,
"workloadType": "<Data Warehouse | Transaction Processing>",
"autonomousDatabaseType": "<Dedicated Infrastructure | Shared Infrastructure>"
}
}
}
These are the event types that Autonomous Container Databases emit:
Change com.oraclecloud.databaseservice.changeautonomouscontainerdatabasecompartment
Compartment
Begin
End
Maintenance com.oraclecloud.databaseservice.autonomous.container.database.maintenance.begin
Begin
Maintenance com.oraclecloud.databaseservice.autonomous.container.database.maintenance.end
End
Maintenance com.oraclecloud.databaseservice.autonomous.container.database.maintenance.reminde
r
Reminder
Maintenance com.oraclecloud.databaseservice.autonomous.container.database.maintenance.schedul
ed
Scheduled
Terminate com.oraclecloud.databaseservice.terminateautonomouscontainerdatabase.begin
Begin
"extensions": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>"
},
"data": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>",
"compartmentName": "example_name",
"resourceName": "my_container_database",
"resourceId": "<unique_ID>",
"availabilityDomain": "all",
"freeFormTags": {},
"definedTags": {},
"additionalDetails": {
"cpuCoreCount": null,
"lifecycleState": "ACTIVE",
"dataStorageSizeInTBs": null,
"timeCreated": "2019-06-27T21:15:59.000Z",
"timeUpdated": "2019-06-27T21:16:04.389Z",
"dbUniqueName": "dwrrdtsr_phx289",
"dbHomeId": "ocid1.autonomoushome.oc1.phx.<unique_ID>",
"dbName": "dwrrdtsr"
"autonomousContainerDatabaseId": "ocid1.autonomouscontainerdatabase.oc1.phx.<unique_ID>"
}
}
}
These are the event types that Autonomous Exadata Infrastructure instances emit:
Change com.oraclecloud.databaseservice.changeautonomousexadatainfrastructurecompartment
Compartmen
t
Maintenance com.oraclecloud.databaseservice.autonomous.exadata.infrastructure.maintenance.begi
n
Begin
Maintenance com.oraclecloud.databaseservice.autonomous.exadata.infrastructure.maintenance.end
End
Maintenance com.oraclecloud.databaseservice.autonomous.exadata.infrastructure.maintenance.remi
nder
Reminder
Maintenance com.oraclecloud.databaseservice.autonomous.exadata.infrastructure.maintenance.sche
duled
Scheduled
Terminate com.oraclecloud.databaseservice.terminateautonomousexadatainfrastructure.begin
Begin
Terminate com.oraclecloud.databaseservice.terminateautonomousexadatainfrastructure.end
End
"contentType": "application/json",
"extensions": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>"
},
"data": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>",
"compartmentName": "example_compartment_name",
"resourceName": "my_exadata_infrastructure_name",
"resourceId": "ocid1.autonomousexainfrastructure.oc1.phx.<unique_ID>",
"availabilityDomain": "XXIT:PHX-AD-3",
"freeFormTags": {},
"definedTags":{},
"additionalDetails":{
"cpuCoreCount": 92,
"lifecycleState": "PROVISIONING",
"dataStorageSizeInTBs": null,
"timeCreated": "2019-07-10T23:13:43.136Z",
"timeUpdated": "2019-07-10T23:28:12.390Z",
"serviceConsoleUrl": null,
"licenseType": null,
"dbName": null
}
}
}
DB System Example
"source": "DatabaseService"
}
"timeUpdated": "2019-07-29T04:43:06.455Z",
"hostName": "ora18c",
"lifecycleDetails": null,
"dbSystemId": "ocid1.dbsystem.oc1.phx.<unique_ID>",
"dbHostId": "DbHost-<unique_ID>",
"nodeNumber": null
}
}
}
"compartmentId": "ocid1.compartment.oc1.<unique_ID>"
},
"data": {
"compartmentId": "ocid1.compartment.oc1.<unique_ID>",
"compartmentName": "example_compartment",
"resourceName": "my_dbhome",
"resourceId": "DbHome-unique_ID",
"availabilityDomain": "all",
"freeFormTags": {},
"definedTags": {},
"additionalDetails": {
"id": "ocid1.id.oc1.<unique_ID>",
"lifecycleState": "PROVISIONING",
"timeCreated": "2019-08-29T12:00:00.000Z",
"timeUpdated": "2019-08-29T12:30:00.000Z",
"lifecycleDetails": "detail message",
"dbSystemId": "DbSystem-unique_ID",
"dbVersion": "19.0.0.0",
"recordVersion": 4,
"displayName": "example_display_name"
}
}
}
Database Example
"definedTags" : {
"My_example_tag_name" :
{ "Example_key" : "Example_value" }
},
"eventID": "<unique_ID>",
"extensions" : {
"compartmentId": "ocid1.compartment.oc1.<unique_ID>"
}
}
These are the event types that Data Guard associations emit:
"additionalDetails": {
"ApplyLag": null,
"DGConfigId": "7e8eff2b-a4cd-474a-abd5-940b05c0b1fd",
"DGConfigState": "null",
"DatabaseId": "ocid1.database.oc1.iad.<unique_ID>",
"DbHomeId": "ocid1.dbhome.oc1.iad.<unique_ID>",
"DbSystemId": "ocid1.dbsystem.oc1.iad.<unique_ID>",
"LastSyncedTime": null,
"SyncState": "null",
"dcsDgUpdateTimestamp": null,
"lastUpdatedIdentifier": null,
"lifeCycleMessage": null,
"lifecycleState": "PROVISIONING",
"timeCreated": "2019-10-25T21:42:19.041Z",
"timeUpdated": "2019-10-25T21:42:19.041Z"
},
"availabilityDomain": "XXIT:US-ASHBURN-AD-1",
"compartmentId": "ocid1.compartment.oc1.<unique_ID>",
"compartmentName": "example_compartment",
"resourceId": "ocid1.dgassociation.oc1.iad.<unique_ID>"
},
"eventID": "5b8b7fbf-2e9a-4730-9761-e52715b7bc79",
"eventTime": "2019-10-25T21:42:16.579Z",
"eventType": "com.oraclecloud.databaseservice.createdataguardassociation.begin",
"eventTypeVersion": "2.0",
"extensions": {
"compartmentId": "ocid1.compartment.oc1.<unique_ID>"
},
"source": "DatabaseService"
}
Data Safe
For details about events emitted by Data Safe, see Oracle Data Safe Events in Oracle Cloud
Infrastructure.
Data Science
Data Science resources that emit events:
l Projects
l Notebook Sessions
l Models
Project Example
"definedTags": {
"Operations": {
"CostCenter": "42"
}
}
},
"extensions": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>"
}
}
{
"eventType": "com.oraclecloud.datascience.updatenotebooksession",
"cloudEventsVersion": "0.1",
"eventTypeVersion": "2.0",
"source": "datascience",
"eventTime": "2019-11-22T01:43:35.246Z",
"eventID": "<unique_ID>",
"contentType": "application/json",
"data": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>",
"compartmentName": "example_compartment",
"resourceName": "example_notebook_session",
"resourceId": "ocid1.datasciencenotebooksession.oc1.iad.<unique_ID>",
"availabilityDomain": "<availability_domain>",
"freeFormTags": {
"Department": "Finance"
},
"definedTags": {
"Operations": {
"CostCenter": "42"
}
}
},
"extensions": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>"
}
}
Model Example
Data Transfer
Data Transfer resources that emit events:
l Jobs
l Appliances
l Packages
l Devices
l Appliance Entitlements
l Appliance Export Jobs
Jobs Examples
{
"eventType": "com.oraclecloud.datatransferservice.addtransferjob",
"source": "datatransferservice",
"eventTypeVersion": "2.0",
"eventTime": "2019-01-10T21:19:24Z",
"contentType": "application/json",
"extensions": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>"
},
"data": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>",
"compartmentName": "example_compartment",
"resourceName": "transfer_job",
"resourceId": "ocid1.datatransferjob.oc1.phx.<unique_ID>",
"availabilityDomain": "<availability_domain>",
"freeFormTags": {
"Department": "Finance"
},
"definedTags": {
"Operations": {
"CostCenter": "42"
}
},
"additionalDetails": {
"deviceType": "APPLIANCE",
"uploadBucketName": "example_bucket",
"lifecycleState": "example_state"
}
}
}
Appliances Example
{
"eventType": "com.oraclecloud.datatransferservice.addtransferappliance",
"source": "datatransferservice",
"eventTypeVersion": "2.0",
"eventTime": "2019-01-10T21:19:24Z",
"contentType": "application/json",
"extensions": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>"
},
"data": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>",
"compartmentName": "example_compartment",
"resourceName": "transfer_job",
"resourceId": "ocid1.datatransferjob.oc1.phx.<unique_ID>",
"availabilityDomain": "<availability_domain>",
"freeFormTags": {
"Department": "Finance"
},
"definedTags": {
"Operations": {
"CostCenter": "42"
}
},
"additionalDetails": {
"applianceLabel": "example_label",
"lifecycleState": "example_state"
}
}
}
Packages Example
{
"eventType": "com.oraclecloud.datatransferservice.addtransferpackage",
"source": "datatransferservice",
"eventTypeVersion": "2.0",
"eventTime": "2019-01-10T21:19:24Z",
"contentType": "application/json",
"extensions": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>"
},
"data": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>",
"compartmentName": "example_compartment",
"resourceName": "transfer_job",
"resourceId": "ocid1.datatransferjob.oc1.phx.<unique_ID>",
"availabilityDomain": "<availability_domain>",
"freeFormTags": {
"Department": "Finance"
},
"definedTags": {
"Operations": {
"CostCenter": "42"
}
},
"additionalDetails": {
"packageLabel": "example_label",
"lifecycleState": "example_state"
}
}
}
Devices Example
{
"eventType": "com.oraclecloud.datatransferservice.addtransferdevice",
"source": "datatransferservice",
"eventTypeVersion": "2.0",
"eventTime": "2019-01-10T21:19:24Z",
"contentType": "application/json",
"extensions": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>"
},
"data": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>",
"compartmentName": "example_compartment",
"resourceName": "transfer_job",
"resourceId": "ocid1.datatransferjob.oc1.phx.<unique_ID>",
"availabilityDomain": "<availability_domain>",
"freeFormTags": {
"Department": "Finance"
},
"definedTags": {
"Operations": {
"CostCenter": "42"
}
},
"additionalDetails": {
"deviceLabel": "example_label",
"lifecycleState": "example_state"
}
}
}
}
}
}
These are the event types that appliance export jobs emit:
}
},
"additionalDetails": {
"bucketName": "example_bucket",
"lifecycleState": "example_state",
"lifecycleStateDetails": "example_details"
}
}
}
Digital Assistant
For details about events emitted by Digital Assistant, see Events for Digital Assistant
Instances.
File Storage
File Storage resources that emit events:
Snapshot Example
Export Example
Functions
Functions resources that emit events:
Application Example
"extensions":{
"compartmentId":"ocid1.compartment.oc1..<unique_ID>"
}
}
Function Example
Health Checks
Health Checks resources that emit events:
l HTTP Monitors
l Ping Monitors
"freeFormTags": {
"Department": "Finance"
},
"definedTags": {
"Operations": {
"CostCenter": "42"
}
}
}
}
"resourceName": "my_monitor",
"resourceId": "ocid1.pingmonitor.oc1..<unique_ID>",
"availabilityDomain": "AD1",
"freeFormTags": {
"Department": "Finance"
},
"definedTags": {
"Operations": {
"CostCenter": "42"
}
}
}
}
IAM
IAM resources that emit events:
Credentials Example
This is a reference event for most credential events (create or reset password don't include
additional details):
{
"eventType": "com.oraclecloud.identityControlPlane.DeleteApiKey",
"cloudEventsVersion": "0.1",
"eventTypeVersion": "2.0",
"source": "identityControlPlane",
"eventID": "<unique_ID>",
"eventTime": "2019-10-21T17:23:54.095Z",
"contentType": "application/json",
"data": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>",
"compartmentName": "example_name",
"resourceName": "my_user",
"resourceId": "<unique_ID>",
"availabilityDomain": "availability_domain",
"freeFormTags": {
"Department": "Finance"
},
"definedTags": {
"Operations": {
"CostCenter": "42"
}
},
"additionalDetails": {
"userId": "ocid1.user.oc1..<unique_ID>"
}
},
"extensions": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>"
}
}
Group Example
This is a reference event for some groups (create, delete, and update events don't include
additional details):
{
"eventType": "com.oraclecloud.identityControlPlane.AddUserToGroup",
"cloudEventsVersion": "0.1",
"eventTypeVersion": "2.0",
"source": "identityControlPlane",
"eventID": "<unique_ID>",
"eventTime": "2019-10-21T17:23:54.095Z",
"contentType": "application/json",
"data": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>",
"compartmentName": "example_name",
"resourceName": "my_group",
"resourceId": "ocid1.groupmembership.oc1.<unique_ID>",
"availabilityDomain": "availability_domain",
"freeFormTags": {
"Department": "Finance"
},
"definedTags": {
"Operations": {
"CostCenter": "42"
}
},
"additionalDetails": {
"userId": "ocid1.user.oc1..<unique_ID>",
"groupId": "ocid1.group.oc1..<unique_ID>"
}
},
"extensions": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>"
}
}
The following reference events are for identity provider events that include additional details.
Some identity providers events do not include additional details. These events are create,
delete, and update identity providers, as well as delete identity provider group, delete IdP
user, and reset IdP SCIM.
This is a reference event for adding and removing users from IdP groups:
{
"eventType": "com.oraclecloud.identityControlPlane.AddUserToIdpGroup",
"cloudEventsVersion": "0.1",
"eventTypeVersion": "2.0",
"source": "identityControlPlane",
"eventID": "<unique_ID>",
"eventTime": "2019-10-21T17:23:54.095Z",
"contentType": "application/json",
"data": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>",
"compartmentName": "example_name",
"resourceName": "my_group",
"resourceId": "ocid1.idpgroup.oc1..<unique_ID>",
"availabilityDomain": "availability_domain",
"freeFormTags": {
"Department": "Finance"
},
"definedTags": {
"Operations": {
"CostCenter": "42"
}
},
"additionalDetails": {
"userId": "ocid1.user.oc1..<unique_ID>"
}
},
"extensions": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>"
}
}
This is a reference event for create, update, and delete IdP group mapping:
{
"eventType": "com.oraclecloud.identityControlPlane.CreateIdpGroupMapping",
"cloudEventsVersion": "0.1",
"eventTypeVersion": "2.0",
"source": "identityControlPlane",
"eventID": "<unique_ID>",
"eventTime": "2019-10-21T17:23:54.095Z",
"contentType": "application/json",
"data": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>",
"compartmentName": "example_name",
"resourceName": "my_identityprovider",
"resourceId": "ocid1.idpgroupmapping.oc1..<unique_ID>",
"availabilityDomain": "availability_domain",
"freeFormTags": {
"Department": "Finance"
},
"definedTags": {
"Operations": {
"CostCenter": "42"
}
},
"additionalDetails": {
"idpGroupName": "my_group",
"groupId": "ocid1.group.oc1..<unique_ID>"
}
},
"extensions": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>"
}
}
This is a reference event for create IdP user and create IdP group:
{
"eventType": "com.oraclecloud.identityControlPlane.CreateIdentityProviderGroup",
"cloudEventsVersion": "0.1",
"eventTypeVersion": "2.0",
"source": "identityControlPlane",
"eventID": "<unique_ID>",
"eventTime": "2019-10-21T17:23:54.095Z",
"contentType": "application/json",
"data": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>",
"compartmentName": "example_name",
"resourceName": "my_idpgroup",
"resourceId": "ocid1.idpgroup.oc1..<unique_ID>",
"availabilityDomain": "availability_domain",
"freeFormTags": {
"Department": "Finance"
},
"definedTags": {
"Operations": {
"CostCenter": "42"
}
},
"additionalDetails": {
"externalIdentifier": "my_externalidentifier"
}
},
"extensions": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>"
}
}
"source": "identityControlPlane",
"eventID": "<unique_ID>",
"eventTime": "2019-10-21T17:23:54.095Z",
"contentType": "application/json",
"data": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>",
"compartmentName": "example_name",
"resourceName": "my_user",
"resourceId": "ocid1.credential.oc1..<unique_ID>",
"availabilityDomain": "availability_domain",
"freeFormTags": {
"Department": "Finance"
},
"definedTags": {
"Operations": {
"CostCenter": "42"
}
},
"additionalDetails": {
"userId": "ocid1.user.oc1..<unique_ID>"
}
},
"extensions": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>"
}
}
Policy Example
User Example
Integration
For details about events emitted by Oracle Integration, see Automating with Events.
Networking
Networking resources that emit events:
l DHCP options
l Dynamic routing gateways (DRGs)
l DRG attachments
l Internet gateways
l Local peering gateways (LPGs)
l NAT gateways
l Network security groups (NSGs)
l Private IPs
l Public IPs
l Route tables
l Security lists
l Service gateways
l Subnets
l Virtual cloud networks (VCNs)
l Virtual network interface cards (VNICs)
l VLANs
These are the event types that sets of DHCP options emit:
"extensions": {
"compartmentId": "ocid1.compartment.oci..<unique_ID>"
}
}
DRG Example
}
},
"eventID": "<unique_ID>",
"extensions": {
"compartmentId": "ocid1.compartment.oci..<unique_ID>"
}
}
"Operations": {
"CostCenter": "42"
}
}
},
"eventID": "<unique_ID>",
"extensions": {
"compartmentId": "ocid1.compartment.oci..<unique_ID>"
}
}
"resourceId": "ocid1.internetgateway.oci.phx.<unique_ID>",
"availabilityDomain": "XXIT:PHX-AD-1",
"freeFormTags": {
"Department": "Finance"
},
"definedTags": {
"Operations": {
"CostCenter": "42"
}
}
},
"eventID": "<unique_ID>",
"extensions": {
"compartmentId": "ocid1.compartment.oci..<unique_ID>"
}
}
Gateway
Gateway
Gateway
LPG Example
Group
Group
Group
NSG Example
}
}
},
"eventID": "<unique_ID>",
"extensions": {
"compartmentId": "ocid1.compartment.oci..<unique_ID>"
}
}
Private IP Example
"definedTags": {
"Operations": {
"CostCenter": "42"
}
}
},
"eventID": "<unique_ID>",
"extensions": {
"compartmentId": "ocid1.compartment.oci..<unique_ID>"
}
}
Public IP Example
"resourceId": "ocid1.publicip.oci.phx.<unique_ID>",
"availabilityDomain": "XXIT:PHX-AD-1",
"freeFormTags": {
"Department": "Finance"
},
"definedTags": {
"Operations": {
"CostCenter": "42"
}
}
},
"eventID": "<unique_ID>",
"extensions": {
"compartmentId": "ocid1.compartment.oci..<unique_ID>"
}
}
"contentType": "application/json",
"data": {
"compartmentId": "ocid1.compartment.oci..<unique_ID>",
"compartmentName": "example_name",
"resourceName": "example_name",
"resourceId": "ocid1.routetable.oci.phx.<unique_ID>",
"availabilityDomain": "XXIT:PHX-AD-1",
"freeFormTags": {
"Department": "Finance"
},
"definedTags": {
"Operations": {
"CostCenter": "42"
}
}
},
"eventID": "<unique_ID>",
"extensions": {
"compartmentId": "ocid1.compartment.oci..<unique_ID>"
}
}
}
}
Subnet Example
"eventID": "<unique_ID>",
"extensions": {
"compartmentId": "ocid1.compartment.oci..<unique_ID>"
}
}
VCN Example
}
}
},
"eventID": "<unique_ID>",
"extensions": {
"compartmentId": "ocid1.compartment.oci..<unique_ID>"
}
}
VNIC Example
},
"eventID": "<unique_ID>",
"extensions": {
"compartmentId": "ocid1.compartment.oci..<unique_ID>"
}
}
VLAN Example
"Department": "Finance"
},
"definedTags": {
"Operations": {
"CostCenter": "42"
}
},
"additionalDetails": {}
}
}
Notifications
Notifications resources that emit events:
l Subscriptions
l Topics
Subscription Example
Topic Example
{
"eventType": "com.oraclecloud.notification.createtopic",
"cloudEventsVersion": "0.1",
"eventTypeVersion": "2.0",
"source": "notification",
"eventTime": "2019-01-10T21:19:24Z",
"contentType": "application/json",
"data":{
"compartmentId": "ocid1.compartment.oc1..<unique_ID>",
"compartmentName": "my_compartment",
"resourceName": "my_topic",
"resourceId": "ocid1.onstopic.oc1..<unique_ID>",
"availabilityDomain": "AD3"
},
"eventID": "<unique_ID>",
"extensions":{
"compartmentId":"ocid1.compartment.oc1..<unique_ID>"
}
}
Object Storage
Object Storage resources that emit events:
l Buckets
l Objects
Bucket Example
Events for objects are handled differently than other resources. Objects do not emit events by
default. Use the Console, CLI, or API to enable a bucket to emit events for object state
changes. You can enable events for object state changes during or after bucket creation.
Object Example
OS Management
For details about events emitted by OS Management, see Creating Automation with Events.
Resource Manager
Resource Manager resources that emit events:
l Jobs
l Stacks
"availabilityDomain": "availability_domain"
},
"eventID": "<unique_ID>",
"extensions": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>"
}
}
"eventID": "<unique_ID>",
"extensions": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>"
}
}
WAF
WAF resources that emit events:
l Waas Policy
l Address List
l Custom Protection Rules
l Certificates
"eventType": "com.oraclecloud.waas.updatewaaspolicy.begin",
"source": "waas",
"eventTypeVersion": "2.0",
"eventTime": "2019-10-11T13:40:54.931962577Z",
"contentType": "application/json",
"extensions": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>"
},
"data": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>",
"compartmentName": "example_name",
"resourceName": "my_waas_policy",
"resourceId": "ocid1.waaspolicy.oc1..<unique_ID>",
"availabilityDomain": "all",
"freeFormTags": {
"Department": "Finance"
},
"definedTags": {
"Operations": {
"CostCenter": "42"
}
},
"additionalDetails": {
"domain": "exmaple.com"
}
}
}
These are the event types that custom protection rules emit:
}
}
}
}
Certificate Example
"Department": "Finance"
},
"definedTags": {
"Operations": {
"CostCenter": "42"
}
}
}
}
Events Metrics
You can monitor performance of your rules by using metrics, alarms, and notifications. This
topic describes the metrics emitted by the metric namespace oci_cloudevents (the Events
service).
Resources: rules. Also measures data for events, which are not resources.
Prerequisites
IAM policies: To monitor resources, 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. The policy must give you access to the monitoring services as well as the
resources being monitored. 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 more information on
user authorizations for monitoring, see the Authentication and Authorization section for the
related service: Monitoring or Notifications.
the quality and scope of the emitted events in your tenancy. For more information, see
Overview of Events.
RESOURCEID
EVENTTYPE
RESOURCEDISPLAYNAME
ACTIONTYPE
One or more of the following types of resources that receives an event from the Events
service.
l Notifications
l Streaming
l Functions
2. Choose the Compartment that contains the rule you want to view, and then click the
rule's name.
3. Click Metrics.
The Metrics page displays a default set of charts for the current rule.
For more information about monitoring metrics and using alarms, see Monitoring Overview.
For information about notifications for alarms, see Notifications Overview.
For more information about monitoring metrics and using alarms, see Monitoring Overview.
For information about notifications for alarms, see Notifications Overview.
Large Compute clusters of thousands of instances can use the File Storage service for high-
performance shared storage. Storage provisioning is fully managed and automatic as your
use scales from a single byte to exabytes without upfront provisioning.
The File Storage service supports the Network File System version 3.0 (NFSv3) protocol. The
service supports the Network Lock Manager (NLM) protocol for file locking functionality.
Oracle Cloud Infrastructure File Storage employs 5-way replicated storage, located in
different fault domains, to provide redundancy for resilient data protection. Data is protected
with erasure encoding.
The File Storage service uses the "eventual overwrite" method of data eradication. Files are
created in the file system with a unique encryption key. When you delete a single file, its
associated encryption key is eradicated, making the file inaccessible. When you delete an
entire file system, the file system is marked as inaccessible. The service systematically
traverses deleted files and file systems, frees all the used space, and eradicates all residual
files.
Use the File Storage service when your application or workload includes big data and
analytics, media processing, or content management, and you require Portable Operating
System Interface (POSIX)-compliant file system access semantics and concurrently
accessible storage. The File Storage service is designed to meet the needs of applications and
users that need an enterprise file system across a wide range of use cases, including the
following:
Tip
Note
MOUNT TARGET
An NFS endpoint that lives in a subnet of your choice and is highly available. The mount
target provides the IP address or DNS name that is used in the mount command when
connecting NFS clients to a file system. A single mount target can export many file
systems. Each mount target can accept up to 896 client connections. By default, you can
create two mount targets per account per availability domain, but you can request an
increase. See Service Limits for a list of applicable limits and instructions for requesting a
limit increase. See Managing Mount Targets for more information about working with this
resource.
EXPORT
Exports control how NFS clients access file systems when they connect to a mount target.
File systems are exported (made available) through mount targets. Each mount target
maintains an export set which contains one or many exports. A file system must have at
least one export in one mount target in order for instances to mount the file system. The
information used by an export includes the file system OCID, mount target OCID, export
set OCID, export path, and client export options. For more information, see Managing
Mount Targets.
EXPORT SET
Collection of one or more exports that control what file systems the mount target exports
using NFSv3 protocol and how those file systems are found using the NFS mount protocol.
Each mount target has an export set. Each file system associated with the mount target
has at least one export in the export set.
EXPORT PATH
A path that is specified when an export is created. It uniquely identifies the file system
within the mount target, letting you associate up to 100 file systems to a single mount
target. This path is unrelated to any path within the file system itself, or the client mount
point path.
The File Storage service adds an export that pairs the file system's Oracle Cloud Identifier
(OCID) and path.
EXPORT OPTIONS
NFS export options are a set of parameters within the export that specify the level of
access granted to NFS clients when they connect to a mount target. An NFS export options
entry within an export defines access for a single IP address or CIDR block range. For
more information, see Working with NFS Export Options.
You can set up a service gateway and give your VCN private access to the File Storage
service. A service gateway can be used only by resources in the gateway's own VCN.
Traffic to the service will not travel through the internet. When creating the service
gateway, enable the service label called All <region> Services in Oracle Services
Network. It includes the File Storage service. Be sure to update route tables for any
subnets that need to access File Storage through the service gateway.
For more information and detailed instructions, see Setting Up a Service Gateway in the
Console
SUBNETS
Subdivisions you define in a VCN (for example, 10.0.0.0/24 and 10.0.1.0/24). Subnets
contain virtual network interface cards (VNICs), which attach to instances. A subnet can
span a region or exist in a single availability domain . A subnet consists of a contiguous
range of IP addresses that do not overlap with other subnets in the VCN. For each subnet,
you specify the routing rules and security lists that apply to it. For more information about
subnets, see VCNs and Subnets in the Oracle Cloud Infrastructure Networking
documentation.
SECURITY RULES
Virtual firewall rules for your VCN. Your VCN comes with a default security list, and you
can add more. These security lists provide ingress and egress rules that specify the types
of traffic allowed in and out of the instances. You can choose whether a given rule is
stateful or stateless. Security list rules must be set up so that clients can connect to file
system mount targets.
Network security groups (NSGs). Another method for applying security rules is to set
them up in a network security group (NSG), and then add the mount target to the NSG.
Unlike security list rules that apply to all VNICs in the subnet, NSGs apply only to resource
VNICs you add to the NSG.
See Security Rules, Security Lists, and Network Security Groups for more information,
examples, and scenarios about how these features interact in your network. Overview of
Networking provides general information about networking. See Configuring VCN Security
Rules for File Storage for more specific information.
SNAPSHOTS
Snapshots provide a consistent, point-in-time view of your file system, and you can take
as many snapshots as you need. You pay only for the storage used by your data and
metadata, including storage capacity used by snapshots. Each snapshot reflects only data
that changed from the previous snapshot. For more information, see Managing Snapshots.
Encryption
The File Storage service encrypts all file system and snapshot data at rest. By default all file
systems are encrypted using Oracle-managed encryption keys. You have the option to encrypt
all of your file systems using the keys that you own and manage using the Vault service. For
more information, see Overview of Vault.
For how to use your own key for new file systems, see Creating File Systems. See To assign a
key to a file system for how to assign or change the key for an existing file system.
Data Transfers
FastConnect offers you the ability to accelerate data transfers. You can leverage the
integration between FastConnect and the File Storage service to perform initial data
migration, workflow data transfers for large files, and disaster recovery scenarios between
two regions, among other things.
Oracle Cloud Infrastructure Compute instances and Oracle Cloud Infrastructure Networking
virtual cloud networks (VCNs).
Oracle Cloud Infrastructure users require resource permissions to create, delete, and manage
resources. Without the appropriate IAM permissions, you cannot export a file system through
a mount target. Until a file system has been exported, Compute instances cannot mount it.
For more information about creating an IAM policy, see Let users create, manage, and delete
file systems.
If you have successfully exported a file system on a subnet, then you use Networking security
lists to control traffic to and from the subnet and, therefore, the mount target. Security lists
act as a virtual firewall, allowing only the network traffic you specify to and from the IP
addresses and port ranges configured in your ingress and egress rules. The security list you
create for the subnet lets hosts send and receive packets and mount the file system. If you
have firewalls on individual instances, use FastConnect, or use a virtual private network
(VPN), the settings for those might also impact security at the networking layer. For more
information about creating a security list for the File Storage service, see Creating File
Systems. See About Security for more information on how different types of security work
together in your file system.
When you create file systems and mount targets, you specify the availability domain they are
created in. All file system data is then stored entirely within the availability domain the file
system resides in. Within an availability domain, the File Storage service uses synchronous
replication and high availability failover to keep your data safe and available.
You cannot move a file system to a different availability domain or region. However, you can
take a snapshot of your data and use a tool such as rsync to copy your data to a different
availability domain or region. See Managing Snapshots for more information on using
snapshots to protect your data.
While it is possible to access mount targets from any availability domain in a region, for
optimal performance, place File Storage resources in the same availability domain as the
Compute instances that access them.
Subnets can be either AD-specific or regional. You can create File Storage resources in either
type of subnet. Regional subnets allow Compute instances to connect to any mount target in
the subnet regardless of AD, with no additional routing configuration. However, to minimize
latency, place mount targets in the same AD as Compute instances just as you would in an
AD-specific subnet. For more information, see About Regional Subnets.
l File systems
l Snapshots
l Mount targets
l Exports
l Export sets
Resource Identifiers
Most types of Oracle Cloud Infrastructure resources have a unique, Oracle-assigned identifier
called an Oracle Cloud ID (OCID). For information about the OCID format and other ways to
identify your resources, see Resource Identifiers.
guide. For a list of available SDKs, see Software Development Kits and Command Line
Interface.
An administrator in your organization needs to set up groups, compartments, and policies that
control which users can access which services, which resources, and the type of access. For
example, the policies control who can create new users, create and manage the cloud
network, launch instances, create buckets, download objects, etc. For more information, see
Getting Started with Policies. For specific details about writing policies for each of the
different services, see Policy Reference.
If you’re a regular user (not an administrator) who needs to use the Oracle Cloud
Infrastructure resources that your company owns, contact your administrator to set up a user
ID for you. The administrator can confirm which compartment or compartments you should be
using.
To set compartment-specific limits on file systems or mount targets, administrators can use
compartment quotas.
About Security
Access Control
The File Storage service uses four different layers of access control. Each layer has its own
authorization entities and methods which are separate from the other layers.
Tip
The Oracle Cloud Infrastructure (OCI) policy layer uses policies to control what users
can do within Oracle Cloud Infrastructure, such as creating instances, a VCN and its security
rules, mount targets, and file systems.
The Network security layer controls which instance IP addresses or CIDR blocks can
connect to a host file system. It uses VCN security list rules to allow or deny traffic to the
mount target, and therefore access to any associated file system.
The NFS export option layer is a method of applying access control per-file system export
based on source IP address that bridges the Network Security layer and the NFS v.3 Unix
Security layer.
The NFS v.3 Unix security layer controls what users can do on the instance, such as
installing applications, creating directories, mounting external file systems by a local mount
point, and reading and writing files.
Oracle Cloud Infrastructure (Oracle Cloud OCI Users and Creating instances and
Infrastructure) policies VCNs. Creating, listing,
and associating file
systems and mount
targets.
You create users and groups in Oracle Cloud Infrastructure. Then, you can use policies to
specify which users and groups can create, access, or modify resources such as file systems,
mount targets, and export options.
The network security layer allows you to use VCN security lists to block the appropriate ports
from specific IP addresses and CIDR blocks and restrict host access. However, it's on an ‘all
or nothing’ basis - the client either can or cannot access the mount target, and therefore all
file systems associated with it. See Working with NFS Export Options to specify granular
controls on a per-file system basis.
File Storage service supports the AUTH_UNIX style of authentication and permission checking
for remote NFS client requests. When mounting file systems, we recommend that you use the
Remember that users in UNIX aren’t the same as users in Oracle Cloud Infrastructure -
they’re not linked or associated in any way. The Oracle Cloud Infrastructure policy layer
doesn’t govern anything that happens inside the file system, the UNIX security layer does.
Conversely, the UNIX security layer doesn’t govern creating file systems or mount targets in
Oracle Cloud Infrastructure.
NFS export options are a method of applying access control at the network security layer and
the NFS v.3 Unix security layer. You can use NFS export options to limit access levels by IP
addresses or CIDR blocks connecting to multiple file systems through exports of an associated
mount target. Access can be restricted so that each client’s file system is inaccessible and
invisible to the other, allowing for managed hosted environment security. Moreover, you can
set permissions for read-only, read/write, or root-squash for your file systems. See Working
with NFS Export Options for more information.
Encryption
All data is encrypted at rest. You can leave all encryption-related matters to Oracle, or you
can choose to manage your own encryption using the Oracle Cloud Infrastructure Vault
(KMS) service. You can use KMS to create master encryption keys and data encryption keys,
rotate keys to generate new cryptographic material, enable or disable keys for use in
cryptographic operations, assign keys to file systems, and use keys for encryption and
decryption. For more information, see Overview of Vault.
In-transit encryption provides a way to secure your data between instances and mounted file
systems using TLS v. 1.2 (Transport Layer Security) encryption.
In-transit encryption is enabled by installing a client package on your instance. The package
creates an NFS endpoint, network namespace, and network interface. A forwarder process
receives requests from the NFS client, encrypts them and sends them to the mount target
using a TLS tunnel.
l Open Network Computing Remote Procedure Call (ONC RPC) rpcbind utility protocol
l Network File System (NFS) protocol
l Network File System (MOUNT) protocol
l Network Lock Manager (NLM) protocol
There are three basic scenarios that require different security rules for File Storage:
l Stateful ingress from ALL ports in source CIDR block to TCP ports 111, 2048, 2049, and
2050.
l Stateful ingress from ALL ports in source CIDR block to UDP ports 111 and 2048.
l Stateful egress from TCP ports 111, 2048, 2049, and 2050 to ALL ports in destination
CIDR block.
l Stateful egress from UDP port 111 to ALL ports in destination CIDR block.
Important
Here's an example of the rules for Scenario A set up for a single subnet that contains both the
mount target and the instance. In this example, both the mount target and the instance are in
CIDR block 10.0.0.0/24:
Security lists are associated with subnets. You can set up the required security rules in the
default security list for the mount target subnet, or create a new security list. Security list
rules apply to all resources in the subnet.
Another method for applying security rules is to set them up in a network security group
(NSG), and then add the mount target to the NSG. Unlike security list rules that apply to all
VNICs in the subnet, NSGs apply only to the resource VNICs you add to the NSG.
See Ways to Enable Security Rules for File Storage for an overview of these methods and
instructions about how to use them to set up security rules.
Set up the following the following security rules for the mount target. Specify the instance IP
address or CIDR block as the source for ingress rules and the destination for egress rules:
l Stateful ingress from ALL ports in the source instance CIDR block to TCP ports 111,
2048, 2049, and 2050.
l Stateful ingress from ALL ports in the source instance CIDR block to UDP ports 111 and
2048.
l Stateful egress from TCP ports 111, 2048, 2049, and 2050 to ALL ports in the
destination instance CIDR block.
l Stateful egress from UDP port 111 ALL ports in the destination instance CIDR block.
Important
Next, set up the following security rules for the instance. Specify the mount target
IP address or CIDR block as the source for ingress rules and the destination for egress rules:
l Stateful ingress from source mount target CIDR block TCP ports 111, 2048, 2049, and
2050 to ALL ports.
l Stateful ingress from source mount target CIDR block UDPport 111 to ALL ports.
l Stateful egress from ALL ports to destination mount target CIDR block TCP ports 111,
2048, 2049, and 2050.
l Stateful egress from ALL ports to destination mount target CIDR block UDP ports 111
and 2048.
Here's an example of the rules for Scenario B set up in security list rules for the instance and
mount target. This example shows rules for specific source and destination CIDR blocks.
Ingress rules for the mount target's NSG or subnet security list. The instance CIDR block
10.0.0.0/24 is the source:
Egress rules for the mount target's NSG or subnet security list. The instance CIDR block
10.0.0.0/24 is the destination:
Ingress rules for the instance's NSG or subnet security list. The mount target CIDR block
10.0.1.0/24 is the source:
Egress rules for the instance's NSG or subnet security list. The mount target CIDR block
10.0.1.0/24 is the destination:
Security lists are associated with subnets. If you use security lists to set up your security
rules, you need to set up the mount target rules in the mount target subnet, and the instance
rules in the instance subnet. You can add the rules to the default security list for each subnet,
or create new security lists.
Another method for applying security rules is to set them up in a network security group
(NSG), and then add the mount target and instance to the NSG. Unlike security list rules that
apply to all VNICs in the subnet, NSGs apply only to resource VNICs you add to the NSG.
See Ways to Enable Security Rules for File Storage for an overview of these methods and
instructions about how to use them to set up security rules.
You can limit the source or destination to the IP address or CIDR block of your choice.
Alternatively, you can allow traffic from all sources or destinations.
l Stateful ingress from ALL ports in the source CIDR block to TCP port 2051.
l Stateful egress from TCP port 2051 to ALL ports in the destination CIDR block.
Security lists are associated with subnets. You can set up the required security rules in the
default security list for the mount target subnet, or create a new security list. Security list
rules apply to all resources in the subnet.
Another method for applying security rules is to set them up in a network security group
(NSG), and then add the mount target to the NSG. Unlike security list rules that apply to all
VNICs in the subnet, NSGs apply only to resource VNICs you add to the NSG.
See Ways to Enable Security Rules for File Storage for an overview of these methods and
instructions about how to use them to set up security rules.
The Networking service offers two virtual firewall features that both use security rules to
control traffic at the packet level. The two features are:
l Security lists: The original virtual firewall feature from the Networking service. When
you create a VCN, a default security list is also created. Add the required rules to the
security list for the subnet that contains the mount target. (If you're setting up Scenario
B: Mount target and instance in different subnets, you have to add rules for both
subnets.) See Setting Up Required Rules in a Security List for instructions.
l Network security groups (NSGs): A subsequent feature designed for application
components that have different security postures. Create an NSG that contains the
required rules, and then add the mount target to the NSG. Alternatively, you can add the
required rules to a previously existing NSG, and add the mount target to the NSG. Each
mount target can belong to up to five (5) NSGs. (If you're setting up Scenario B: Mount
target and instance in different subnets, you have to add both the mount target and
instance to an NSG that contains the required security rules.) See Setting Up Required
Rules in a Network Security Group (NSG) for instructions.
Important
See Security Rules, Security Lists, and Network Security Groups for more information,
examples, and scenarios about how these features interact in your network. Overview of
Networking provides general information about networking. See About Security for
information about how security rules work with other types of security in File Storage.
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: The policy in Let network admins manage a cloud network covers
management of all networking components, including security lists and NSGs. See the Policy
Reference for more information.
If you're new to policies, see Getting Started with Policies and Common Policies.
You can add the required rules to a pre-existing security list associated with a subnet, such as
the default security list that is created along with the VCN. See To create a security list for
more information.
4. On the details page for the cloud network, in Resources, and then click Security
Lists.
5. Click the name of the security list used by the subnet.
6. In Resources, click Ingress Rules.
7. Click Add Ingress Rules.
l Specify that it's a stateful rule by leaving the check box clear. (For more
information about stateful and stateless rules, see Stateful Versus Stateless
Rules). By default, rules are stateful unless you specify otherwise.
l To allow traffic from the subnet of the cloud network, click Source Type, choose
CIDR, and then enter the CIDR block for the subnet. For example, 10.0.0.0/24.
l Click IP Protocol, and then choose the protocol. For example, TCP.
l In Source Port Range, specify the range of ports that you want to allow traffic
from. Alternatively, accept the default of All to allow traffic from any source port.
l Click Destination Port Range, and then enter individual ports or a port range.
For example, 2048-2050.
8. Click + Additional Ingress Rule to create more ingress rules.
9. When you're done, click Add Ingress Rules.
10. Next, create the egress rules. In Resources, click Egress Rules.
11. Click Add Egress Rules.
l Specify that it's a stateful rule by leaving the check box clear.
l Click Destination Type, choose CIDR, and then enter the CIDR block for the
subnet. For example, 10.0.0.0/24.
l Click IP Protocol, and then choose the protocol. For example, TCP.
l In Source Port Range, and then enter individual ports or a port range. For
example, 2048-2050.
l In Destination Port Range, accept the default of All to allow traffic to any
destination port.
The general process for setting up NSGs that work with File Storage is:
1. Create an NSG with the required security rules. (Alternatively, you can add them to a
previously existing NSG.)
2. Add the mount target (or more specifically, the mount target's VNIC) to the NSG. You
can do this when you create the mount target, or you can update the mount target and
add it to one or more NSGs that contain the required security rules.
3. If you're setting up Scenario B: Mount target and instance in different subnets, you'll
have to add both the mount target and instance to an NSG that contains the required
security rules.
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 Network Security Groups.
4. Click Create Network Security Group.
5. Enter the following:
l Name: A descriptive name for the network security group. The name doesn't
have to be unique, and you can change it later. Avoid entering confidential
information.
l Create in Compartment: The compartment where you want to create the
network security group, if different from the compartment you're currently
working in.
l Show Tagging Options: Optionally, you can apply 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.
6. Click Next.
7. Enter ingress rules.
l Specify that it's a stateful rule by leaving the check box clear. (For more
information about stateful and stateless rules, see Stateful Versus Stateless
Rules). By default, rules are stateful unless you specify otherwise.
l In Direction, choose Ingress.
l To allow traffic from the subnet of the cloud network, click Source Type, choose
CIDR, and then enter the CIDR block for the subnet. For example, 10.0.0.0/24.
l Click IP Protocol, and then choose the protocol. For example, TCP.
l In Source Port Range, specify the range of ports that you want to allow traffic
from. Alternatively, accept the default of All to allow traffic from any source port.
l Click Destination Port Range, and then enter individual ports or a port range.
For example, 2048-2050.
8. Click + Another Rule to create more ingress rules.
9. Enter egress rules.
l Specify that it's a stateful rule by leaving the check box clear.
l In Direction, choose Egress.
l Click Destination Type, choose CIDR, and then enter the CIDR block for the
subnet. For example, 10.0.0.0/24.
l Click IP Protocol, and then choose the protocol. For example, TCP.
l In Source Port Range, and then enter individual ports or a port range. For
example, 2048-2050.
l In Destination Port Range, accept the default of All to allow traffic to any
destination port.
10. Click + Another Rule to create more egress rules.
11. When you're done, click Create.
Overview
NFS export options enable you to create more granular access control than is possible using
just security list rules to limit VCN access. You can use NFS export options to specify access
levels for IP addresses or CIDR blocks connecting to file systems through exports in a mount
target. Access can be restricted so that each client’s file system is inaccessible and invisible to
the other, providing better security controls in multi-tenant environments.
Using NFS export option access controls, you can limit clients' ability to connect to the file
system and view or write data. For example, if you want to allow clients to consume but not
update resources in your file system, you can set access to Read Only. You can also reduce
client root access to your file systems and map specified User IDs (UIDs) and Group IDs
(GIDs) to an anonymous UID/GID of your choice. For more information about how NFS export
options work with other security layers, see About Security.
Tip
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: The policy in Let users create, manage, and delete file systems allows
users to manage NFS export options.
If you're new to policies, see Getting Started with Policies and Common Policies.
Exports
Exports control how NFS clients access file systems when they connect to a mount target. File
systems are exported (made available) through mount targets. Each mount target maintains
an export set which contains one or many exports.A file system may be exported through one
or more mount targets. A file system must have at least one export in one mount target in
order for instances to mount the file system. The information used by an export includes the
file system OCID, mount target OCID, export set OCID, export path, and client export
options.Typically, an export is created in a mount target when the file system is created.
Thereafter, you can create additional exports for a file system in any mount target that
resides in the same availability domain as the file system.
NFS Export Options
NFS export options are a set of parameters within the export that specify the level of access
granted to NFS clients when they connect to a mount target. An NFS export options entry
within an export defines access for a single IP address or CIDR block range.
Each separate client IP address or CIDR block you want to define access for needs a separate
export options entry in the export. For example, if you want to set options for NFS client IP
addresses 10.0.0.6, 10.0.08, and 10.0.0.10, you need to create three separate entries, one for
each IP address.
File Storage service considers the listed order of each export options entry for the export.
During an NFS request by a client, File Storage service applies the first set of options that
matches the client Source IP address. Only the first set is applied; the rest are ignored.
For example, consider the following two export options entries specifying access for an
export:
In this case, clients who connect to the export from IP address 10.0.0.8 have Read Only
access. The request Source IP address is contained in the CIDR block specified in the first
entry, and File Storage Service applies the options in the first match.
Important
Important
l Access (Read_Only, Read_Write): This setting specifies the source NFS client
access. If unspecified, defaults to Read_Write.
l Identity Squash: (All, Root, None): This setting determines whether the source
clients accessing the file system have their User ID (UID) and Group ID (GID)
remapped to anonymousUid and anonymousGid. If you choose All, all users and
groups are remapped. If Root, only the root user UID/GID combination 0/0 is
remapped. If None, no users are remapped. If unspecified, defaults to None.
l anonymousUid: This setting is used along with the Identity Squash option. When
remapping users, you can use this setting to change the default anonymousUid of
65534 to any user ID of your choice.
l anonymousGid: This setting is used along with the Identity Squash option. When
remapping groups, you can use this setting to change the default anonymousGid of
65534 to any group ID of your choice.
When you create file system and export, the NFS export options for that file system are set to
the following defaults, which allow full access for all NFS client source connections. These
defaults must be changed if you want to restrict access:
Provide a managed hosted environment for two clients. The clients share a mount target, but
each has their own file system, and cannot access each other's data. For example:
l Client A, who is assigned to CIDR block 10.0.0.0/24, requires Read/Write access to file
system A, but not file system B.
l Client B, who is assigned to CIDR block 10.1.1.0/24, requires Read/Write access to file
system B, but not file system A.
l Client C, who is assigned to CIDR block 10.2.2.0/24, has no access of any kind to file
system A or file system B.
l Both file systems A and B are associated to a single mount target, MT1. Each file system
has an export contained in the export set of MT1.
Since Client A and Client B access the mount target from different CIDR blocks, you can set
the client options for both file system exports to allow access to only a single CIDR block.
Client C is denied access by not including its IP address or CIDR block in the NFS export
options for any export of either file system.
Console Example
Set the export options for file system A to allow Read/Write access only to Client A, who is
assigned to CIDR block 10.0.0.0/24. Client B and Client C are not included in this CIDR block,
and cannot access the file system.
Set the export options for file system B to allow Read/Write access only to Client B, who is
assigned to CIDR block 10.1.1.0/24. Client A and Client C are not included in this CIDR block,
and cannot access the file system.
CLI Example
Set the export options for file system A to allow Read_Write access only to Client A, who is
assigned to CIDR block 10.0.0.0/24. Client B and Client C are not included in this CIDR block,
and cannot access the file system.
oci fs export update --export-id <File_system_A_export_ID> --export-options '
[{"source":"10.0.0.0/24","require-privileged-source-port":"true","access":"READ_WRITE","identity-
squash":"NONE","anonymous-uid":"65534","anonymous-gid":"65534"}]'
Set the export options for file system B to allow Read_Write access only to Client B, who is
assigned to CIDR block 10.1.1.0/24. Client A and Client C are not included in this CIDR block,
and cannot access the file system.
oci fs export update --export-id <File_system_B_export_ID> --export-options '[{"source":"10.1.1.0/24
","require-privileged-source-port":"true","access":"READ_WRITE","identity-squash":"NONE","anonymous-
uid":"65534","anonymous-gid":"65534"}]'
API Example
Set the export options for file system A to allow READ_WRITE access only to Client A, who is
assigned to CIDR block 10.0.0.0/24. Client B and Client C are not included in this CIDR block,
and cannot access the file system.
PUT/<Current_API_Version>/exports/<File_System_A_export_OCID>
Host: filestorage.us-phoenix-1.oraclecloud.com
<authorization and other headers>
{
"exportOptions": [
{
"source": "10.0.0.0/24",
"requirePrivilegedSourcePort": true,
"access": "READ_WRITE",
"identitySquash": "NONE",
"anonymousUid": 65534,
"anonymousGid": 65534
}
]
}
Set the export options for file system B to allow READ_WRITE access only to Client B, who is
assigned to CIDR block 10.1.1.0/24. Client A and Client C are not included in this CIDR block,
and cannot access the file system.
PUT/<Current_API_Version>/exports/<File_System_B_export_OCID>
Host: filestorage.us-phoenix-1.oraclecloud.com
<authorization and other headers>
{
"exportOptions": [
{
"source": "10.1.1.0/24",
"requirePrivilegedSourcePort": true,
"access": "READ_WRITE",
"identitySquash": "NONE",
"anonymousUid": 65534,
"anonymousGid": 65534
}
]
}
Provide data to customers for consumption, but don't allow them to update the data.
For example, you'd like to publish a set of resources in file system A for an application to
consume, but not change. The application connects from IP address 10.0.0.8.
Console Example
Set the source IP address 10.0.0.8 to Read Only in the export for file system A:
CLI Example
Set the source IP address 10.0.0.8 to READ_ONLY in the export for file system A:
oci fs export update --export-id <File_System_A_export_OCID> --export-options '
[{"source":"10.0.0.8","require-privileged-source-port":"true","access":"READ_
ONLY","identitysquash":"NONE","anonymousuid":"65534","anonymousgid":"65534"}]'
API Example
Set the source IP address 10.0.0.8 to READ_ONLY in the export for file system A:
PUT/<Current_API_Version>/exports/<File_System_A_export_OCID>
Host: filestorage.us-phoenix-1.oraclecloud.com
<authorization and other headers>
{
"exportOptions": [
{
"source": "10.0.0.8",
"requirePrivilegedSourcePort": true,
"access": "READ_ONLY",
"identitySquash": "NONE",
"anonymousUid": 65534,
"anonymousGid": 65534
}
]
}
To increase security, you'd like to limit the root user's privileges when connecting to File
System A. Use Identity Squash to remap root users to UID/GID 65534. In Unix-like systems,
this UID/GID combination is reserved for 'nobody', a user with no system privileges.
Console Example
CLI Example
oci fs export update --export-id <File_System_A_export_OCID> --export-options '
[{"source":"0.0.0.0/0","require-privileged-source-port":"true","access":"READ_
WRITE","identitysquash":"ROOT","anonymousuid":"65534","anonymousgid":"65534"}]'
API Example
PUT/<Current_API_Version>/exports/<File_System_A_export_OCID>
Host: filestorage.us-phoenix-1.oraclecloud.com
<authorization and other headers>
{
"exportOptions": [
{
"source": "0.0.0.0/0",
"requirePrivilegedSourcePort": true,
"access": "READ_WRITE",
"identitySquash": "ROOT",
"anonymousUid": 65534,
"anonymousGid": 65534
}
]
}
Tip
Tip
For information about using the CLI, see Command Line Interface (CLI).
To create an export
Open a command prompt and run oci fs export create to create an export for a specified
file system within a specified export set. This example creates an export along with its NFS
export options.
For example:
oci fs export create --export-set-id <export_set_OCID> --file-system-id <file_system_OCID> --path
"</pathname>" --export-options '
[{"source":"10.0.0.0/16","requireprivilegedsourceport":"true","access":"READWRITE","identitysquash":"NO
NE","anonymousuid":"0","anonymousgid":"0"}]'
Important
Examples:
Acceptable:
Not Acceptable:
/ and /example
/example/
/example/path/../example1
For example:
oci fs export update --export-id <export_OCID> --export-options '[{"source":"<0.0.0.0/0>","require-
privileged-source-port":"true","access":"READ_ONLY","identity-squash":"ROOT","anonymous-
uid":"65534","anonymous-gid":"65534"}]'
WARNING: Updates to export-options will replace any existing values. Are you sure you want to continue?
[y/N]: y
Tip
To list exports
Open a command prompt and run oci fs export list to list all exports in a specified
compartment.
For example:
oci fs export list --compartment-id target_compartment_id
To delete an export
Open a command prompt and run oci fs export delete to delete an export.
For example:
Warning
l CreateExport
l UpdateExport
l ListExports
l GetExport
l DeleteExport
l For general information about getting started with file systems, see Overview of File
Storage.
l For more information on the Vault service, see Overview of Vault.
l For more information on securing your file system, see About Security and the Securing
File Storage reference in the Security Guide.
In-transit encryption doesn't require any updates to your file system's mount target or export
configuration. To enable in-transit encryption, you install a package called oci-fss-utils on
your instance. The oci-fss-utils package creates a network namespace and virtual network
interface on your instance and provides a local NFS endpoint. The oci-fss-utils package
also runs a forwarder process in the background called oci-fss-fowarder.
The network namespace isolates the forwarder process from your instance’s networking
environment. The virtual network interface provides the forwarder process a unique IP
address. The local NFS endpoint provides NFS connection capability.
The file system is mounted using a special command that initiates encryption. After the file
system is mounted, the oci-fss-forwarder process connects the local NFS client to the NFS
endpoint. The process then receives requests from the NFS client, encrypts them and sends
them to the mount target using a TLS tunnel.
1. Download the oci-fss-utils package. For instructions, see Task 1: Download the OCI-
FSS-UTILS package
2. Install the oci-fss-utils package on the instance. For instructions, see Task 2: Install
the OCI-FSS-UTILS package on Oracle Linux or CentOS
3. Use the in-transit encryption command to mount the file system. For instructions, see
Task 3: Mount the file system with the encryption command
l The in-transit encryption installation package is distributed as an RPM for Oracle Linux
and CentOS and can be downloaded at cloud-infrastructure-file-storage-downloads.html
l You must install the oci-fss-utils package on every instance that requires encrypted
access to a mount target.
l The number of encrypted NFS/TLS connections for a single mount target is limited to 64.
This limitation is caused by TLS memory requirements. Unlike NFS connections, TLS
connections do not share memory buffers. So, once a TLS connection has been
established, the allocated memory stays dedicated to it.
PREREQUISITES
l Add the following new rules to the security list for the mount target subnet.
Alternatively, you can add the following rules to a Network Security Group (NSG) and
then add the mount target to the NSG. For more information and instructions about
adding security list rules for File Storage, see Configuring VCN Security Rules for File
Storage.
o A stateful ingress rule allowing TCP traffic to a Destination Port Range of
2051.
o A stateful egress rule allowing TCP traffic from a Source Port Range of 2051.
Important
S ETUP TASKS
The scp command requires an SSH key pair to authenticate a remote user. If your instances
are UNIX-style systems, you probably already have the ssh-keygen utility installed. To
determine if it's installed, open a shell or terminal and type ssh-keygen on the command line.
If it's not installed, you can obtain OpenSSH for UNIX from
http://www.openssh.com/portable.html.
After the RPM package is downloaded to the target instance, proceed to Task 2: Install
the OCI-FSS-UTILS package on Oracle Linux or CentOS.
The package creates a namespace called ns1 in your instance, which contains a default
network interface for ethernet traffic. A network interface pair is created for each mount
target.
After the package has finished installing, proceed to Task 3: Mount the file system with the
encryption command.
Replace 10.x.x.x: with the local subnet IP address assigned to your mount target, fs-
export-path with the export path you specified when associating the file system with
the mount target, and yourmountpoint with the path to the local mount point. The
export path is the path to the file system (relative to the mount target IP address or
hostname).
Example output from the mount -t oci-fss command:
Created symlink from /etc/systemd/system/multi-user.target.wants/oci-fss-2.service to
/usr/lib/systemd/system/oci-fss-2.service.
Each time you mount a file system using this command, a new oci-fss service is
initiated with an incrementing sequence number between 2 and 255. For example, oci-
fss-2.service, oci-fss-3.service, and so on.
Tip
1. Open a terminal window on the instance. Mount the file system as described in Task 2:
Install the OCI-FSS-UTILS package on Oracle Linux or CentOS.
2. Open the /etc/fstab file for editing:
cd /etc
vi fstab
Replace 10.x.x.x: with the local subnet IP address assigned to your mount target, fs-
export-path with the export path you specified when associating the file system with
the mount target, and yourmountpoint with the path to the local mount point.
Tip
Troubleshooting
If you experience issues with in-transit encryption, try the following techniques:
VERIFY THAT YOU HAVE ALL THE SECURITY LIST RULES SET UP CORRECTLY FOR THE MOUNT TARGET SUBNET .
l A stateful ingress rule allowing TCP traffic to a Destination Port Range of 2051.
l A stateful egress rule allowing TCP traffic from a Source Port Range of 2051.
VERIFY THAT THE OCI-FSS SERVICE IS RUNNING FOR THE MOUNTED FILE SYSTEM.
For example:
Created symlink from /etc/systemd/system/multi-user.target.wants/oci-fss-2.service to
/usr/lib/systemd/system/oci-fss-2.service.
VERIFY THAT THE NAMESPACE NS1 HAS BEEN CREATED AND CONTAINS A NETWORK INTERFACE .
You should see output displaying all the ethernet devices within namespace ns1. For
example:
1: lo: <LOOPBACK> mtu 65536 qdisc noop state DOWN mode DEFAULT group default qlen 1000
link/loopback 00:00:00:00:00:00 brd 00:00:0
3: v-peer1@if4: <BROADCAST,MULTICAST,UP,LOW
DEFAULT group default qlen 1000
link/ether be:5b:35:2d:e9:54 brd ff:ff:ff:ff:ff:ff
An output value of 1 means that IP forwarding is enabled. This value is read from the
/proc/sys/net/ipv4/ip_forward file.
If the output value is 0, then IP forwarding is not enabled for the instance. Enable
IP forwarding by following the instructions in To enable IP forwarding on the instance.
USE THE TCPDUMP UTILITY TO ANALYZE TRAFFIC BETWEEN THE OCI-FSS SERVICE AND THE NFS CLIENT .
USE THE JOURNALCTL COMMAND TO VIEW ANY MESSAGES THAT MAY HAVE BEEN LOGGED BY SYSTEMD
-f displays the most recent journal entries, and prints new entries as they are appended to
the journal.
Warning
For administrators: The policy in Let users create, manage, and delete file systems allows
users to create file systems. Since mount targets are network endpoints, users must also
have "use" permissions for VNICs, private IPs, private DNS zones, and subnets to create or
delete a mount target. See the Policy Reference for more information.
If you're new to policies, see Getting Started with Policies and Common Policies.
Prerequisites
Before you create a file system, you need:
l At least one Virtual Cloud Network (VCN) in a compartment. For more information, see
VCNs and Subnets.
l Correctly configured security rules for the file system mount target. Security rules can
be created in the security list for the mount target subnet, or in a Network Security
Group (NSG) that you add the mount target to. See Security Rules for information about
how security rules work in Oracle Cloud Infrastructure. Use the instructions in
Configuring VCN Security Rules for File Storage to set up security rules correctly for
your file systems
Note
4. You can choose to accept the system defaults, or change them by clicking Edit Details.
Warning
o Tags: Optionally, you can apply 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.
l Export Information
Mount targets use exports to manage access to file systems. The path name
uniquely identifies the file system within the mount target, and is used by an
instance to mount the file system.
o Export Path: The File Storage service creates a default export path using
the file system name. Optionally, replace the default export path name with
a new path name, preceded by a forward slash (/). For example, /fss. This
value specifies the mount path to the file system (relative to the mount
target IP address or hostname). Avoid entering confidential information.
Important
Warning
Note
Warning
Important
o Subnet: The most recently created subnet listed in the selected availability
domain is used as default. Subnets can be either AD-specific or regional
(regional ones have "regional" after the name). For more information, see
VCNs and Subnets.
5. If you want to accept the defaults for the mount target, click Create. The file system is
created with the information displayed. If you want to choose another mount target or
change the default information, click the Edit Details link.
6. In the Mount Target Information section, specify details for the mount target that is
associated with the file system:
l Select an Existing Mount Target: Choose this option if you want to associate
the file system with a mount target you already created. Choose the Mount
Target from the list. Click the click here link in the dialog box if you want to
enable compartment selection for the mount target.
Tip
l Create a New Mount Target: Choose this option if you want to create a new
mount target associated with this file system. By default, the mount target is
created in your current compartment and you can use network resources in that
compartment. Click the click here link in the dialog box if you want to enable
compartment selection for the mount target, its VCN, or subnet resources.
Important
Note
Important
l Subnet: Select a subnet to attach the mount target to. Subnets can be either AD-
specific or regional (regional ones have "regional" after the name). For more
information, see VCNs and Subnets.
Warning
Note
8. Click Create.
The File Storage service typically creates the file system and mount target within seconds.
Next, mount the file system from an instance so that you can read and write directories and
files in your file system. See Mounting File Systems for instructions about obtaining mount
commands for your operating system type and mounting your file system.
Warning
File systems use Oracle-managed keys by default, which leaves all encryption-related
matters to Oracle. Optionally, you can encrypt the data in this file system using your own
Vault encryption key. For more information, see Overview of Vault.
For example:
oci fs file-system create --availability-domain AAbC:US-ASHBURN-AD-1 --display-name "My File System" --
compartment-id ocid1.compartment.oc1..<unique_id> --kms-key-id --kms-key-id ocid1.key.oc1.phx.<unique_
id>
Warning
Open a command prompt and run oci fs mount-target create to create a mount target.
For example:
oci fs mount-target create --availability-domain <target_availability domain> --compartment-id <target_
compartment_id> --subnet-id <subnet_OCID> --display-name “<My Mount Target>”
Warning
To create an export
An export is a file system together with the path that can be used to mount it. Each export
resource belongs to one export set.
Open a command prompt and run oci fs export create to create an export for a specified
file system within a specified export set.
For example:
oci fs export create --export-set-id <export_set_OCID> --file-system-id <file_system_OCID> --path
"</pathname>"
Important
Acceptable:
Not Acceptable:
/ and /example
/example/
/example/path/../example1
Warning
Note
l CreateFileSystem
l CreateMountTarget
l CreateExport
files to the file system from the instance. Windows operating systems use a drive letter
assignment instead of a mount point to represent root access.
Prerequisites
l The file system must have at least one export in at least one mount target. When you
create a new file system, an export for the file system is created at the same time. See
Creating File Systems for more information.
l Correctly configured security rules for the mount target. See Security Rules for
information about how security rules work in Oracle Cloud Infrastructure. Use the
instructions in Configuring VCN Security Rules for File Storage to set up security rules
correctly for your file systems.
l Oracle Linux
l CentOS
l Debian
l Red Hat Linux
l Ubuntu
Here's an example of the information contained in a mount command sample. The file system
name is used to create directory names:
Mount command samples mount the file system at the file system root directory. Mount
command samples don't include subdirectory information for the file system. If you want to
mount a subdirectory of the file system, you must edit the sample to append the subdirectory
path to the export path. For more information on mounting subdirectories in Linux-type
instances, see To mount a file system subdirectory (Linux). For more information on mounting
subdirectories in Windows instances, see To mount a file system subdirectory (Windows).
Warning
Note
For administrators: The policy in Let users create, manage, and delete file systems allows
users to obtain mount commands.
If you're new to policies, see Getting Started with Policies and Common Policies.
The Console displays a list of file systems that have already been created in the
compartment, if any.
3. Find the file system you want to mount, click the Actions icon (three dots), and then
click View File System Details.
4. In Resources, click Exports.
5. Find the export in the mount target you want to use to mount the file system, click the
Actions icon (three dots), and then click Mount Commands.
Tip
6. In Image, choose the image of the Compute instance you want to mount the file system
to.
7. Click the Copy link to copy the commands.
Prerequisites
l The file system must have at least one export in at least one mount target. When you
create a new file system, an export for the file system is created at the same time. See
Creating File Systems for more information.
l Correctly configured security rules for the mount target. See Security Rules for
information about how security rules work in Oracle Cloud Infrastructure. Use the
instructions in Configuring VCN Security Rules for File Storage to set up security rules
correctly for your file systems.
You can use the following instructions to construct your mount commands, or use the Console
to get mount command samples that include all the information for a specific mount target
and file system. For more information, see To get mount command samples.
Mount command samples mount the file system at the file system root directory. Mount
command samples don't include subdirectory information for the file system. If you want to
mount your Linux-type instance at a subdirectory of the file system, you must edit the sample
to append the subdirectory path to the export path. For more information, see To mount a file
system subdirectory.
Warning
Note
2. Create a mount point by copying and pasting the Create Mount Point Command from
the Console or type the following, replacing yourmountpoint with the local directory
from which you want to access your file system.
sudo mkdir -p /mnt/yourmountpoint
3. Mount the file system by copying and pasting the Mount Command from the Console
or type the following:
sudo mount -o nosuid,resvport 10.x.x.x:/fs-export-path /mnt/yourmountpoint
l Replace 10.x.x.x: with the local subnet IP address assigned to your mount
target.
l Replace fs-export-path with the export path you specified when associating the
file system with the mount target.
l Replace yourmountpoint with the path to the local mount point.
Tip
Warning
Note
5. Write a file to the file system by typing the following. Replace yourmountpoint with the
path to the local mount point and helloworld with your file name.
6. Verify that you can view the file by typing the following. Replace yourmountpoint with
the path to the local mount point.
cd /mnt/yourmountpoint
ls
See Mount Command Fails in Troubleshooting Your File System for more information about
common issues you may encounter.
2. Create a mount point by copying and pasting the Create Mount Point Command from
the Console or type the following, replacing yourmountpoint with the local directory
from which you want to access your file system.
sudo mkdir -p /mnt/yourmountpoint
3. Mount the file system by copying and pasting the Mount Command from the Console
or type the following:
sudo mount -o nosuid,resvport 10.x.x.x:/fs-export-path /mnt/yourmountpoint
l Replace 10.x.x.x: with the local subnet IP address assigned to your mount
target.
l Replace fs-export-path with the export path you specified when associating the
file system with the mount target.
l Replace yourmountpoint with the path to the local mount point.
Tip
Warning
Note
5. Write a file to the file system by typing the following. Replace yourmountpoint with the
path to the local mount point and helloworld with your file name.
6. Verify that you can view the file by typing the following. Replace yourmountpoint with
the path to the local mount point.
cd /mnt/yourmountpoint
ls
See Mount Command Fails in Troubleshooting Your File System for more information about
common issues you may encounter. See if you want to mount a subdirectory of the file
system.
3. Use the chkconfig command to enable starting rpcbind service at system startup.
sudo chkconfig rpcbind on
4. Change the default configuration of iptables to include the mount target IP address and
allow traffic by typing the following. Replace 10.x.x.x with the local subnet address
assigned to the mount target for the file system. Save the new iptables entries.
sudo iptables -A INPUT -p tcp -s 10.x.x.x -j ACCEPT
5. Create a mount point by typing the following, replacing yourmountpoint with the local
directory from which you want to access your file system.
sudo mkdir -p /mnt/yourmountpoint
6. Mount the file system by copying and pasting the Mount Command from the Console
or type the following:
sudo mount -t nfs -o nosuid,resvport,tcp,vers=3 10.x.x.x:/fs-export-path /mnt/yourmountpoint
l Replace 10.x.x.x: with the local subnet IP address assigned to your mount
target.
l Replace fs-export-path with the export path you specified when associating the
file system with the mount target.
l Replace yourmountpoint with the path to the local mount point.
Tip
Warning
Note
See Mount Command Fails in Troubleshooting Your File System for more information about
common issues you may encounter.
1. Open a command window. Then, mount the file system using the steps described in the
previous section.
2. Type the following command to get the file system entry point:
sudo cat /etc/mtab |grep -i nfs
3. Copy the file system entry point, and open the /etc/fstab file:
cd /etc
vi fstab
Warning
Important
Note
See Mount Command Fails in Troubleshooting Your File System for more information about
common issues you may encounter.
If your file system has an existing directory structure, you can mount any file system
subdirectory. The subdirectory becomes the effective root directory at the mount point of the
instance, and excludes sibling directories.
For example, suppose "FileSystem1" has an export path of /FileSystem1 and a directory
structure like this:
The following command mounts directoryA to the instance mount point /mnt/mymountpoint:
sudo mount -o nosuid,resvport 10.0.0.16:/FileSystem1/rootdirectory/directoryA /mnt/mymountpoint
Neither directoryB or FileB would be accessible from the instance mount point.
Warning
2. Create a mount point by copying and pasting the Create Mount Point Command from
the Console or type the following, replacing yourmountpoint with the local directory
from which you want to access your file system.
sudo mkdir -p /mnt/yourmountpoint
3. Mount the file system by copying and editing the Mount Command from the Console or
type the following:
sudo mount -o nosuid,resvport 10.x.x.x:/fs-export-path/directory-path /mnt/yourmountpoint
l Replace 10.x.x.x: with the local subnet IP address assigned to your mount
target.
l Replace fs-export-path with the export path you specified when associating the
file system with the mount target.
l Replace directory-path with the path from the root directory to subdirectory
you want to mount.
l Replace yourmountpoint with the path to the local mount point.
Tip
Warning
Note
5. Write a file to the file system by typing the following. Replace yourmountpoint with the
path to the local mount point and helloworld with your file name.
6. Verify that you can view the file by typing the following. Replace yourmountpoint with
the path to the local mount point.
cd /mnt/yourmountpoint
ls
When a file system is created, its root directory is owned by the root user. If you're
connecting from an Oracle-provided Linux or CentOS instance, the default user is opc. If
you're connecting from an Oracle-provided Ubuntu instance, the default user is ubuntu. These
default users are not root users, so you can't initially write a file or directory to a new file
system with these users. Depending on your security requirements, there are several ways to
proceed:
l Connect as the root user. Then, create files or directories in the new file system.
l Connect as the root user. Then, change the ownership or permissions of the file system
root directory to allow other users (such as opc or ubuntu) to write to the file system.
l Connect as the root user. Then, create subdirectories with ownership or permissions
that allow other users to write to the subdirectory.
Learn more about updating file and directory ownership and permissions.
l Connect as the default user. Then, use the sudo command to write or to change
permissions or ownership of files or directories. The sudo command temporarily
provides a regular user with root user permissions. Here's an example of using the sudo
command to write to the file system:
sudo touch /mnt/yourmountpoint/helloworld
The Windows NFS client must be installed on the instance from which you want to mount the
file system.
Warning
Access to NFS file systems requires UNIX-style user and group identities, which are not the
same as Windows user and group identities. To enable users to access NFS shared resources,
Windows client for NFS accesses file systems anonymously, using AnonymousGid and
AnonymousUid. On brand new file systems, write permissions are only granted to the root
user. The AnonymousGid and AnonymousUid identity values must be configured to allow write
access.
Warning
After you have installed the NFS client and correctly mapped user identities, you can mount
the file system to any available drive letter using the command line or Map network drive.
You can access your file system through the chosen drive letter to write files.
Prerequisites
l The file system must have at least one export in at least one mount target. When you
create a new file system, an export for the file system is created at the same time. See
Warning
Note
Important
Important
4. In the standard Windows Command Line (CMD) window, mount the file system by typing
the following. Replace 10.x.x.x: with the local subnet IP address assigned to your
mount target, fs-export-path with the export path you specified when associating the
file system with the mount target, and X with the drive letter of any available drive you
want to map the file system to.
mount 10.x.x.x:/fs-export-path X:
Tip
Important
5. Write a file to the file system by typing the following. Replace X with the drive letter you
used in step 10 and helloworld with your file name.
X:
6. Verify that you can view the file by typing the following.
dir
See Troubleshooting Windows NFS Connections for more information about common issues
you might encounter.
Warning
Important
9. Open File Explorer and select This PC. In the Computer tab, select Map network
drive.
10. Select the Drive letter that you want to assign to the file system.
11. In the Folder field, enter the following. Replace 10.x.x.x with the local subnet IP
address assigned to your mount target, and fs-export-path with the export path you
specified when associating the file system with the mount target.
\\10.x.x.x\fs-export-path
Tip
Important
See Troubleshooting Windows NFS Connections for more information about common issues
you might encounter.
If your file system has an existing directory structure, you can mount any file system
subdirectory. The subdirectory becomes the effective root directory at the mount point of the
instance, and excludes sibling directories.
For example, suppose "FileSystem1" has an export path of /FileSystem1 and a directory
structure like this:
Warning
b. If you're Using Windows File Explorer , enter the following in the Folder field of
the drive letter you want to map the file system to (step 11):
l Replace 10.x.x.x: with the local subnet IP address assigned to your mount
target.
The compartment has policies that indicate what actions a user can take to manage file
system. UNIX permissions control what actions a user can take on the files stored in the file
system. See About Security for more information.
You can perform most administrative tasks for your file systems using the Console, Command
Line Interface (CLI), or API. You can use the Console to list mount targets exporting a specific
file system. Use the API or CLI if you want to list all mount targets in a compartment.
To access a file system, it must have at least one export in one mount target. Next, mount the
file system from an instance, and then you can create directories and read and write files. For
more information about creating an export for a file system, see To create an export for a file
system in this topic. For more information about accessing your file system, see Mounting File
Systems.
For administrators: The policy in Let users create, manage, and delete file systems allows
users to manage file systems.
If you're new to policies, see Getting Started with Policies and Common Policies.
Tagging Resources
You can apply tags to your resources to help you organize them according to your business
needs. You can apply tags at the time you create a resource, or you can update the resource
later with the desired tags. For general information about applying tags, see Resource Tags.
AVAILABILITY DOMAIN
When you create a file system, you specify the availability domain that it resides in. An
availability domain is one or more data centers located within a region. You need your file
system's availability domain to use the Command Line Interface (CLI) or the API. For
more information, see Regions and Availability Domains.
CREATED
The date and time that the file system was created.
COMPARTMENT
When you create a file system, you specify the compartment that it resides in. A
compartment is a collection of related resources (such as cloud networks, compute
instances, or file systems) that are only accessible to those groups that have been given
permission by an administrator in your organization. You need your file system's
compartment to use the Command Line Interface (CLI) or the API. For more information,
see Managing Compartments.
UTILIZATION
Metered size of the file system that gets updated hourly. For more information, see File
System Usage and Metering.
RESOURCES
Resources such as exports and snapshots that are associated with the file system are
listed here. Click the resource type link to see a list of each individual resource. Each
export in the list shows the file system's export path and mount target. You need the
export path to mount a file system.
Warning
1. Open the navigation menu. Under Core Infrastructure, click File Storage and then
click File Systems.
2. In the List Scope section, select a compartment.
3. To view information about a file system, find the file system, click the Actions icon
(three dots), and then click View File System Details.
1. Open the navigation menu. Under Core Infrastructure, click File Storage and then
click File Systems.
2. In the List Scope section, select a compartment.
3. To view information about a file system, find the file system, click the Actions icon
(three dots), and then click View File System Details.
4. Click Rename.
5. Enter the new file system name, and click Rename.
1. Open the navigation menu. Under Core Infrastructure, click File Storage and then
click File Systems.
2. In the left-hand navigation, in the List Scope section, under Compartment, select a
compartment.
3. Click the name of the file system you want to create an export for, and click Create
Export.
Note
4. You can choose to accept the system defaults, or change them by clicking Edit Details.
5. If you want to accept the defaults for the mount target, click Create. The file system is
created with the information displayed. If you want to choose another mount target or
change the default information, click the Edit Details link.
6. In the Mount Target Information section, specify details for the mount target that is
associated with the file system:
l Select an Existing Mount Target: Choose this option if you want to associate
the file system with a mount target you already created. Choose the Mount
Target from the list. Click the click here link in the dialog box if you want to
enable compartment selection for the mount target.
Tip
l Create a New Mount Target: Choose this option if you want to create a new
mount target associated with this file system. By default, the mount target is
created in your current compartment and you can use network resources in that
compartment. Click the click here link in the dialog box if you want to enable
compartment selection for the mount target, its VCN, or subnet resources.
Important
Note
Important
Warning
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. Optionally, click Show Advanced Options to configure the mount target's advanced
options.
l IP Address: You can specify an unused IP address in the subnet you selected for
the mount target.
l Hostname: You can specify a hostname you want to assign to the mount target.
Note
8. Click Create.
Next, mount the file system from an instance so that you can read and write directories and
files in your file system. See Mounting File Systems for instructions about obtaining mount
commands for your operating system type and mounting your file system.
Important
1. Open the navigation menu. Under Core Infrastructure, click File Storage and then
click File Systems.
2. In the List Scope section, select a compartment.
3. Find the mount target you're interested in, click the Actions icon (three dots), and then
click View File System Details.
4. In Exports, click on the mount target name.
5. Click the Reported Size (in GiB) Edit or the Reported Inodes (in Gil) icon.
6. Enter the maximum free space in gibibytes or the maximum inodes in gibinodes you
want the File Storage service to report.
7. Click the Save icon.
Important
The file system is moved immediately. Moving a file system doesn't affect mounted instances.
Warning
Prerequisites:
l At least one key vault and key in the Vault service. For more information, see Overview
of Vault.
l Correctly set permissions that allow the File Storage service to use keys. For example:
Allow service FssOc1Prod to use keys in compartment <compartment_name>
1. Open the navigation menu. Under Core Infrastructure, click File Storage and then
click File Systems.
2. Under List Scope, in the Compartment list, choose the compartment that contains the
file system that you want to encrypt with a Vault master encryption key.
3. From the list of file systems, click the file system name.
1. Open the navigation menu. Under Core Infrastructure, click File Storage and then
click File Systems.
2. Under List Scope, in the Compartment list, choose the compartment that contains the
file system that you want to encrypt with a Vault master encryption key.
3. From the list of file systems, click the file system name.
4. Next to Encryption Key, click Edit.
5. In Encryption Type, select Encrypt using Oracle-managed keys.
6. When you are finished, click Save Changes.
Warning
1. Open the navigation menu. Under Core Infrastructure, click File Storage and then
click File Systems.
2. In the List Scope section, select a compartment.
3. Find the file system you want to delete.
4. Click the Actions icon (three dots), and then click View File System Details.
5. Delete all of the file system's exports:
l In Exports, select the check box for all exports listed, and then click Delete.
6. When all of the exports are deleted, click Delete to delete the file system.
The file system is deleted immediately, along with all of its snapshots.
For example:
For example:
oci fs file-system get --file-system-id <file_system_OCID>
For example:
oci fs file-system update --file-system-id <file_system_OCID> --display-name "<New File System Name>"
Warning
options.Typically, an export is created in a mount target when the file system is created.
Thereafter, you can create additional exports for a file system in any mount target that
resides in the same availability domain as the file system.
Open a command prompt and run oci fs export create to create an export for a specified
file system within a specified export set.
For example:
oci fs export create --export-set-id <export_set_OCID> --file-system-id <file_system_OCID> --path
"</pathname>"
Important
Acceptable:
Not Acceptable:
/ and /example
/example/
/example/path/../example1
Warning
Note
Customers can define how much free capacity is reported as available to the operating
system.
Important
Warning
Prerequisites:
l At least one key vault and key in the Vault service. For more information, see Overview
of Vault.
l Correctly set permissions that allow the File Storage service to use keys. For example:
Allow service FssOc1Prod to use keys in compartment <compartment_name>
Open a command prompt and run oci fs file-system update to update the file system
with a new key.
oci fs file-system update --file-system-id <file_system_OCID> --kms-key-id <target_key_id>
For example:
Open a command prompt and run oci fs file-system update. Leave the --kms-key-id
value unspecified.
oci fs file-system update --file-system-id <file_system_OCID> --kms-key-id ""
For example:
oci fs file-system update --file-system-id ocid1.filesystem.oc1.phx.<unique_id> --kms-key-id ""
Open a command prompt and run oci fs file-system delete to delete a file system.
For example:
oci fs file-system delete --file-system-id <file_system_OCID>
Warning
l ListFileSystems
l GetFileSystem
l UpdateFileSystem
l ChangeFileSystemCompartment
l DeleteFileSystem
Overview
Actions you can take to manage a mount target include:
You can perform most administrative tasks for your mount targets using the Console,
Command Line Interface (CLI), or API. You can use the Console to list mount targets exporting
a specific file system. Use the API or CLI if you want to list all mount targets in a
compartment.
Mount Target
A mount target is an NFS endpoint that lives in a VCN subnet of your choice and provides
network access for file systems. The mount target provides the IP address or DNS name that
is used together with a unique export path to mount the file system. A single mount target can
export many file systems. Typically, you create your first mount target and export when you
create your first file system. The mount target maintains an export set which contains all of
the exports for its associated file systems.
Exports
Exports control how NFS clients access file systems when they connect to a mount target. File
systems are exported (made available) through mount targets. Each mount target maintains
an export set which contains one or many exports. A file system may be exported through one
or more mount targets. A file system must have at least one export in one mount target in
order for instances to mount the file system. The information used by an export includes the
file system OCID, mount target OCID, export set OCID, export path, and client export
options.Typically, an export is created in a mount target when the file system is created.
Thereafter, you can create additional exports for a file system in any mount target that
resides in the same availability domain as the file system.
NFS Export Options
NFS export options are a set of parameters within the export that specify the level of access
granted to NFS clients when they connect to a mount target. An NFS export options entry
within an export defines access for a single IP address or CIDR block range.
See Service Limits for a list of applicable limits and instructions for requesting a limit
increase.
l However, you can export up to 100 file systems through each mount target.
l Each mount target can accept up to 896 client connections.
l Each mount target requires three internal IP addresses in the subnet to function:
o Two of the IP addresses are used during mount target creation. The third IP
address must remain available for the mount target to use for high availability
failover.
o The third IP address is used to create a new VNIC for the mount target during
failover. The original primary IP address is retained.
o The File Storage service doesn't "reserve" the third IP address required for high
availability failover.
o Use care to ensure that enough unallocated IP addresses remain available for
your mount targets to use during failover.
o Do not use /30 or smaller subnets for mount target creation because they do not
have sufficient available IP addresses for mount target creation.
For administrators: The policy in Let users create, manage, and delete file systems allows
users to manage mount targets. Since mount targets are network endpoints, users must also
have "use" permissions for VNICs, private IPs, private DNS zones, and subnets to create or
delete a mount target. See the Policy Reference for more information.
If you're new to policies, see Getting Started with Policies and Common Policies.
Tagging Resources
You can apply tags to your resources to help you organize them according to your business
needs. You can apply tags at the time you create a resource, or you can update the resource
later with the desired tags. For general information about applying tags, see Resource Tags.
CREATED
The date and time that the mount target was created.
AVAILABILITY DOMAIN
When you create a mount target, you specify the availability domain that it resides in. An
availability domain is one or more data centers located within a region. You need your
mount target's availability domain to use the Command Line Interface (CLI) or the API.
For more information, see Regions and Availability Domains.
COMPARTMENT
When you create a mount target, you specify the compartment that it resides in. A
compartment is a collection of related resources (such as cloud networks, compute
instances, or file systems) that are accessible only to those groups that have been given
permission by an administrator in your organization. You need your mount target's
compartment to use the Command Line Interface (CLI) or the API. For more information,
see Managing Compartments.
SUBNET
The subnet within the VCN where the mount target VNIC resides. Subnets can be either
AD-specific or regional (regional ones have "regional" after the name). For more
information, see VCNs and Subnets.
IP ADDRESS
The IP address that was assigned to the mount target when it was created. You need your
mount target's IP address to mount associated file systems.
HOSTNAME
The hostname that was assigned to the mount target, if any. For more information about
hostnames, see DNS in Your Virtual Cloud Network.
EXPORTS
All of the mount target's exports are listed here. The export path and name of each file
system is also listed. You need the export path to mount a file system.
Warning
Important
1. Open the navigation menu. Under Core Infrastructure, click File Storage and then
click Mount Targets.
2. In the List Scope section, select a compartment.
The Console displays a list of mount targets that have already been created in the
compartment, if any.
3. Click Create Mount Target.
4. Enter the required mount target information. Click the click here link in the dialog box
if you want to enable compartment selection for the mount target, its VCN, or subnet
resources:
l New Mount Target Name: Optionally, replace the default with a friendly name
for the mount target. It doesn't have to be unique; an Oracle Cloud Identifier
(OCID) uniquely identifies the mount target. Avoid entering confidential
information.
Note
Important
Warning
5. Optionally, click Show Advanced Options to configure the mount target's advanced
options.
l IP Address: You can specify an unused IP address in the subnet you selected for
the mount target.
l Hostname: You can specify a hostname you want to assign to the mount target.
Note
6. Click Create.
Note
1. Open the navigation menu. Under Core Infrastructure, click File Storage and then
click Mount Targets.
2. In the List Scope section, select a compartment.
3. To view information about a file system, find the file system, click the Actions icon
(three dots), and then click View Mount Target Details.
4. Click Rename.
5. Enter the new mount target name, and click Rename.
1. Open the navigation menu. Under Core Infrastructure, click File Storage and then
click Mount Targets.
2. In the left-hand navigation, in the List Scope section, under Compartment, select a
compartment.
3. Click the name of the mount target you want to create an export for, and click Create
Export.
Note
4. You can choose to accept the system defaults, or change them by clicking Edit Details.
5. Click Create.
Next, mount the file system from an instance so that you can read and write directories and
files in your file system. See Mounting File Systems for instructions about obtaining mount
commands for your operating system type and mounting your file system.
system size reported to the operating system by setting the Reported Size or Reported
Inodes value in the file system's mount target. Typically, setting the size to 1024 GiB and the
inodes to 1024 GiI permits successful installation.
Important
1. Open the navigation menu. Under Core Infrastructure, click File Storage and then
click Mount Targets.
2. In the List Scope section, select a compartment.
3. Find the mount target you're interested in, click the Actions icon (three dots), and then
click View Mount target Details.
4. Click the Reported Size (in GiB) Edit or the Reported Inodes (in Gil) icon.
5. Enter the maximum size in gibibytes or the maximum inodes in gibiinodes you want the
File Storage service to report.
6. Click the Save icon.
Important
To delete an export
Note
1. Open the navigation menu. Under Core Infrastructure, click File Storage and then
click Mount Targets.
2. In the List Scope section, select a compartment.
3. Find the mount target you're interested in, click the Actions icon (three dots), and then
click View Mount target Details.
4. In Exports, find the export you want to delete.
5. Click the Actions icon (three dots), and then click Delete.
1. Open the navigation menu. Under Core Infrastructure, click File Storage and then
click Mount Targets.
2. In the List Scope section, select a compartment.
3. Find the mount target you're interested in, click the Actions icon (three dots), and then
click View Mount Target Details.
4. In the Mount Target Information tab, click the Edit link next to Network Security
Groups.
5. Select a Compartment and NSG from the list.
6. Click Save.
Warning
Warning
Open a command prompt and run oci fs mount-target create to create a mount target.
For example:
oci fs mount-target create --availability-domain <target_availability domain> --compartment-id <target_
compartment_id> --subnet-id <subnet_OCID> --display-name “<My Mount Target>”
Warning
You can create a mount target that is added to a network security group (NSG).
For example:
oci fs mount-target create --availability-domain <target_availability domain> --compartment-id <target_
compartment_id> --subnet-id <subnet_OCID> --display-name “<My Mount Target>" --nsg-ids '["<nsg_OCID_
1>","<nsg_OCID_2"]'
For example:
oci fs mount-target update --mount-target-id <mount_target_OCID> --display-name "<New Mount Target
Name>" --nsg-ids '["<nsg1_OCID>", "<nsg2_OCID>"]'
Warning
For example:
oci fs mount-target delete --mount-target-id <mount_target_OCID>
Warning
Open a command prompt and run oci fs mount-target list to list all mount targets in a
specified availability domain and compartment.
For example:
oci fs mount-target list --availability-domain <target_availability_domain> --compartment-id <target_
compartment_OCID>
For example:
oci fs mount-target get --mount-target-id <mount_target_OCID>
To create an export
Exports control how NFS clients access file systems when they connect to a mount target. File
systems are exported (made available) through mount targets. Each mount target maintains
an export set which contains one or many exports. A file system may be exported through one
or more mount targets. A file system must have at least one export in one mount target in
order for instances to mount the file system. The information used by an export includes the
file system OCID, mount target OCID, export set OCID, export path, and client export options.
Typically, an export is created in a mount target when the file system is created. Thereafter,
you can create additional exports for a file system in any mount target that resides in the
same availability domain as the file system.
Open a command prompt and run oci fs export create to create an export for a specified
file system within a specified export set.
For example:
oci fs export create --export-set-id <export_set_OCID> --file-system-id <file_system_OCID> --path
"</pathname>"
Important
Acceptable:
Not Acceptable:
/ and /example
/example/
/example/path/../example1
Warning
Note
To list exports
Open a command prompt and run oci fs export list to list all exports in a specified
compartment.
For example:
oci fs export list --compartment-id <target_compartment_id>
For example:
oci fs export get --export-id <export_OCID>
To delete an export
Open a command prompt and run oci fs export delete to delete an export.
For example:
oci fs export delete --export-id <export_OCID>
Warning
For example:
oci fs export-set list --availability-domain <target_availability_domain> --compartment-id <target_
compartment_OCID>
For example:
oci fs export-set get --export-set-id <export_set_OCID>
For example:
oci fs export-set update --export-set-id <export_set_OCID> --display-name "<New Export Set Name>"
Important
Important
Overview
NFS export options enable you to create more granular access control than is possible using
just security list rules to limit VCN access. You can use NFS export options to specify access
levels for IP addresses or CIDR blocks connecting to file systems through exports in a mount
target. Access can be restricted so that each client’s file system is inaccessible and invisible to
the other, providing better security controls in multi-tenant environments.
Using NFS export option access controls, you can limit clients' ability to connect to the file
system and view or write data. For example, if you want to allow clients to consume but not
update resources in your file system, you can set access to Read Only. You can also reduce
client root access to your file systems and map specified User IDs (UIDs) and Group IDs
(GIDs) to an anonymous UID/GID of your choice. For more information about how NFS export
options work with other security layers, see About Security.
Tip
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: The policy in Let users create, manage, and delete file systems allows
users to manage NFS export options.
If you're new to policies, see Getting Started with Policies and Common Policies.
Exports
Exports control how NFS clients access file systems when they connect to a mount target. File
systems are exported (made available) through mount targets. Each mount target maintains
an export set which contains one or many exports.A file system may be exported through one
or more mount targets. A file system must have at least one export in one mount target in
order for instances to mount the file system. The information used by an export includes the
file system OCID, mount target OCID, export set OCID, export path, and client export
options.Typically, an export is created in a mount target when the file system is created.
Thereafter, you can create additional exports for a file system in any mount target that
resides in the same availability domain as the file system.
NFS Export Options
NFS export options are a set of parameters within the export that specify the level of access
granted to NFS clients when they connect to a mount target. An NFS export options entry
within an export defines access for a single IP address or CIDR block range.
Each separate client IP address or CIDR block you want to define access for needs a separate
export options entry in the export. For example, if you want to set options for NFS client IP
addresses 10.0.0.6, 10.0.08, and 10.0.0.10, you need to create three separate entries, one for
each IP address.
File Storage service considers the listed order of each export options entry for the export.
During an NFS request by a client, File Storage service applies the first set of options that
matches the client Source IP address. Only the first set is applied; the rest are ignored.
For example, consider the following two export options entries specifying access for an
export:
In this case, clients who connect to the export from IP address 10.0.0.8 have Read Only
access. The request Source IP address is contained in the CIDR block specified in the first
entry, and File Storage Service applies the options in the first match.
Important
Important
l Access (Read_Only, Read_Write): This setting specifies the source NFS client
access. If unspecified, defaults to Read_Write.
l Identity Squash: (All, Root, None): This setting determines whether the source
clients accessing the file system have their User ID (UID) and Group ID (GID)
remapped to anonymousUid and anonymousGid. If you choose All, all users and
groups are remapped. If Root, only the root user UID/GID combination 0/0 is
remapped. If None, no users are remapped. If unspecified, defaults to None.
l anonymousUid: This setting is used along with the Identity Squash option. When
remapping users, you can use this setting to change the default anonymousUid of
65534 to any user ID of your choice.
l anonymousGid: This setting is used along with the Identity Squash option. When
remapping groups, you can use this setting to change the default anonymousGid of
65534 to any group ID of your choice.
When you create file system and export, the NFS export options for that file system are set to
the following defaults, which allow full access for all NFS client source connections. These
defaults must be changed if you want to restrict access:
Provide a managed hosted environment for two clients. The clients share a mount target, but
each has their own file system, and cannot access each other's data. For example:
l Client A, who is assigned to CIDR block 10.0.0.0/24, requires Read/Write access to file
system A, but not file system B.
l Client B, who is assigned to CIDR block 10.1.1.0/24, requires Read/Write access to file
system B, but not file system A.
l Client C, who is assigned to CIDR block 10.2.2.0/24, has no access of any kind to file
system A or file system B.
l Both file systems A and B are associated to a single mount target, MT1. Each file system
has an export contained in the export set of MT1.
Since Client A and Client B access the mount target from different CIDR blocks, you can set
the client options for both file system exports to allow access to only a single CIDR block.
Client C is denied access by not including its IP address or CIDR block in the NFS export
options for any export of either file system.
Console Example
Set the export options for file system A to allow Read/Write access only to Client A, who is
assigned to CIDR block 10.0.0.0/24. Client B and Client C are not included in this CIDR block,
and cannot access the file system.
Set the export options for file system B to allow Read/Write access only to Client B, who is
assigned to CIDR block 10.1.1.0/24. Client A and Client C are not included in this CIDR block,
and cannot access the file system.
CLI Example
Set the export options for file system A to allow Read_Write access only to Client A, who is
assigned to CIDR block 10.0.0.0/24. Client B and Client C are not included in this CIDR block,
and cannot access the file system.
oci fs export update --export-id <File_system_A_export_ID> --export-options '
[{"source":"10.0.0.0/24","require-privileged-source-port":"true","access":"READ_WRITE","identity-
squash":"NONE","anonymous-uid":"65534","anonymous-gid":"65534"}]'
Set the export options for file system B to allow Read_Write access only to Client B, who is
assigned to CIDR block 10.1.1.0/24. Client A and Client C are not included in this CIDR block,
and cannot access the file system.
oci fs export update --export-id <File_system_B_export_ID> --export-options '[{"source":"10.1.1.0/24
","require-privileged-source-port":"true","access":"READ_WRITE","identity-squash":"NONE","anonymous-
uid":"65534","anonymous-gid":"65534"}]'
API Example
Set the export options for file system A to allow READ_WRITE access only to Client A, who is
assigned to CIDR block 10.0.0.0/24. Client B and Client C are not included in this CIDR block,
and cannot access the file system.
PUT/<Current_API_Version>/exports/<File_System_A_export_OCID>
Host: filestorage.us-phoenix-1.oraclecloud.com
<authorization and other headers>
{
"exportOptions": [
{
"source": "10.0.0.0/24",
"requirePrivilegedSourcePort": true,
"access": "READ_WRITE",
"identitySquash": "NONE",
"anonymousUid": 65534,
"anonymousGid": 65534
}
]
}
Set the export options for file system B to allow READ_WRITE access only to Client B, who is
assigned to CIDR block 10.1.1.0/24. Client A and Client C are not included in this CIDR block,
and cannot access the file system.
PUT/<Current_API_Version>/exports/<File_System_B_export_OCID>
Host: filestorage.us-phoenix-1.oraclecloud.com
<authorization and other headers>
{
"exportOptions": [
{
"source": "10.1.1.0/24",
"requirePrivilegedSourcePort": true,
"access": "READ_WRITE",
"identitySquash": "NONE",
"anonymousUid": 65534,
"anonymousGid": 65534
}
]
}
Provide data to customers for consumption, but don't allow them to update the data.
For example, you'd like to publish a set of resources in file system A for an application to
consume, but not change. The application connects from IP address 10.0.0.8.
Console Example
Set the source IP address 10.0.0.8 to Read Only in the export for file system A:
CLI Example
Set the source IP address 10.0.0.8 to READ_ONLY in the export for file system A:
oci fs export update --export-id <File_System_A_export_OCID> --export-options '
[{"source":"10.0.0.8","require-privileged-source-port":"true","access":"READ_
ONLY","identitysquash":"NONE","anonymousuid":"65534","anonymousgid":"65534"}]'
API Example
Set the source IP address 10.0.0.8 to READ_ONLY in the export for file system A:
PUT/<Current_API_Version>/exports/<File_System_A_export_OCID>
Host: filestorage.us-phoenix-1.oraclecloud.com
<authorization and other headers>
{
"exportOptions": [
{
"source": "10.0.0.8",
"requirePrivilegedSourcePort": true,
"access": "READ_ONLY",
"identitySquash": "NONE",
"anonymousUid": 65534,
"anonymousGid": 65534
}
]
}
To increase security, you'd like to limit the root user's privileges when connecting to File
System A. Use Identity Squash to remap root users to UID/GID 65534. In Unix-like systems,
this UID/GID combination is reserved for 'nobody', a user with no system privileges.
Console Example
CLI Example
oci fs export update --export-id <File_System_A_export_OCID> --export-options '
[{"source":"0.0.0.0/0","require-privileged-source-port":"true","access":"READ_
WRITE","identitysquash":"ROOT","anonymousuid":"65534","anonymousgid":"65534"}]'
API Example
PUT/<Current_API_Version>/exports/<File_System_A_export_OCID>
Host: filestorage.us-phoenix-1.oraclecloud.com
<authorization and other headers>
{
"exportOptions": [
{
"source": "0.0.0.0/0",
"requirePrivilegedSourcePort": true,
"access": "READ_WRITE",
"identitySquash": "ROOT",
"anonymousUid": 65534,
"anonymousGid": 65534
}
]
}
Tip
Tip
For information about using the CLI, see Command Line Interface (CLI).
To create an export
Open a command prompt and run oci fs export create to create an export for a specified
file system within a specified export set. This example creates an export along with its NFS
export options.
For example:
oci fs export create --export-set-id <export_set_OCID> --file-system-id <file_system_OCID> --path
"</pathname>" --export-options '
[{"source":"10.0.0.0/16","requireprivilegedsourceport":"true","access":"READWRITE","identitysquash":"NO
NE","anonymousuid":"0","anonymousgid":"0"}]'
Important
Examples:
Acceptable:
Not Acceptable:
/ and /example
/example/
/example/path/../example1
For example:
oci fs export update --export-id <export_OCID> --export-options '[{"source":"<0.0.0.0/0>","require-
privileged-source-port":"true","access":"READ_ONLY","identity-squash":"ROOT","anonymous-
uid":"65534","anonymous-gid":"65534"}]'
WARNING: Updates to export-options will replace any existing values. Are you sure you want to continue?
[y/N]: y
Tip
To list exports
Open a command prompt and run oci fs export list to list all exports in a specified
compartment.
For example:
oci fs export list --compartment-id target_compartment_id
To delete an export
Open a command prompt and run oci fs export delete to delete an export.
For example:
Warning
l CreateExport
l UpdateExport
l ListExports
l GetExport
l DeleteExport
Managing Snapshots
The File Storage service supports snapshots for data protection of your file system. Snapshots
are a consistent, point-in-time view of your file systems. Snapshots are copy-on-write, and
scoped to the entire file system. The File Storage service encrypts all file system and
snapshot data at rest. You can take as many snapshots as you need.
Data usage is metered against differentiated snapshot data. If nothing has changed within the
file system since the last snapshot was taken, the new snapshot does not consume more
storage. For more information, see File System Usage and Metering.
Snapshots are accessible under the root directory of the file system at .snapshot/name. For
data protection, you can use a tool that supports NFSv3 to copy your data to a different
availability domain, region, file system, object storage, or remote location.
For best performance, we recommend that you use the parallel tar (partar) and parallel copy
(parcp) tools provided in the File Storage Parallel File Toolkit for this purpose. These tools
work best with parallel workloads and requests. The Parallel File Toolkit is available for
Oracle Linux, Red Hat Enterprise Linux, and CentOS. You can use rsync or regular tar for
other operating system types. See To install the Parallel File Tools suite for more information.
Tip
Warning
For administrators: The policy in Let users create, manage, and delete file systems allows
users to create and delete snapshots.
If you're new to policies, see Getting Started with Policies and Common Policies.
Tagging Resources
You can apply tags to your resources to help you organize them according to your business
needs. You can apply tags at the time you create a resource, or you can update the resource
later with the desired tags. For general information about applying tags, see Resource Tags.
To create a snapshot
1. Open the navigation menu. Under Core Infrastructure, click File Storage and then
click File Systems.
2. In the List Scope section, select a compartment.
3. In the File Systems list, locate the file system you want to take a snapshot of. Click
the Actions icon (three dots), and then click View File System Details.
4. In Resources, click Snapshots.
5. Click Create Snapshot.
6. Fill out the required information:
l Name: Enter a name for the snapshot. It must be unique among all other
snapshots for this file system. The name can't be changed. Avoid entering
confidential information.
7. Click Create Snapshot. The snapshot is accessible under the root directory of the file
system at .snapshot/name.
3. In the File Systems list, locate the file system you took the snapshot of. Click the
Actions icon (three dots), and then click View File System Details.
4. In Resources, click Snapshots.
5. In the Snapshots list, locate the snapshot you're interested in. Click the Actions icon
(three dots), and then click View Snapshot Details.
3. Use the mkdir command to create a directory in the hidden .snapshot directory. The
directory you create is the snapshot. Give the snapshot a name that will help you
identify it. Avoid using confidential information in the snapshot name. For example:
mkdir snapshot-Jan1
4. Use the ls command to verify that your snapshot has been created in the .snapshot
directory.
ls
The tool suite is distributed as an RPM for Oracle Linux, Red Hat Enterprise Linux, and CentOS.
man parcp
man parrm
To restore a snapshot
Snapshots are created under the root folder of your file system, in a hidden directory named
.snapshot.
You can restore a file within the snapshot, or an entire snapshot using the cp command. Use
the -r option when restoring a snapshot that contains subdirectories.
For example:
cp -r .snapshot/snapshot_name/* destination_directory_name
Optionally, you can use rsync, tar, or another tool that supports NFSv3 to copy your data to
another remote location. For optimal performance, use the Parallel File Tools.
For example:
parcp .snapshot/snapshot_name/* destination_directory_name
To delete a snapshot
1. Open the navigation menu. Under Core Infrastructure, click File Storage and then
click File Systems.
2. In the List Scope section, select a compartment.
3. Find the file system with the snapshot you want to delete.
4. Click the Actions icon (three dots), and then click View File System Details.
5. In Resources, click Snapshots.
6. Find the snapshot you want to delete.
7. Click Delete.
To create a snapshot
You can create a snapshot of a file system. A snapshot is a point-in-time view of the file
system. The snapshot is accessible at ./shapshot/name.
Open a command prompt and run oci fs snapshot create to create a snapshot of a file
system.
For example:
oci fs snapshot create --file-system-id <file_system_OCID> --name "<January1>"
Warning
To list snapshots
Open a command prompt and run oci fs snapshot create to list all snapshots associated
with a specific file system.
For example:
oci fs snapshot list --file-system-id <file_system_OCID>
specific snapshot.
For example:
oci fs snapshot get --snapshot-id <snapshot_OCID>
To delete a snapshot
Open a command prompt and run oci fs snapshot delete to delete a snapshot.
For example:
oci fs snapshot delete --snapshot-id <snapshot_OCID>
This topic describes the metrics emitted by the metric namespace oci_filestorage (the File
Storage service).
operations are producing unexpected errors. You can get visibility into your workload IOPs
and latency, and set up alarms to receive notifications if tolerance thresholds are exceeded.
Metrics provided for file systems can be filtered or grouped by their associated mount target.
l The mean for each 5-minute interval is calculated over 5 raw data points.
l The mean for each 60-minute interval is calculated over 60 raw data points.
authorizations for monitoring, see the Authentication and Authorization section for the related
service: Monitoring or Notifications.
You also can use the Monitoring service to create custom queries.
RESOURCEID
MOUNTTARGETID
THROUGHPUT
SIZE
HEALTHITEM
This shows this information... using these that you can use
chart... defaults.... to...
This shows this information... using these that you can use
chart... defaults.... to...
This shows this information... using these that you can use
chart... defaults.... to...
notifications
when
operation
bytes per
second for a
larger group
size is too
high.
This shows this information... using these that you can use
chart... defaults.... to...
This shows this information... using these that you can use
chart... defaults.... to...
latency
exceeds
tolerance, so
you can take
action.
This shows this information... using these that you can use
chart... defaults.... to...
This shows this information... using these that you can use
chart... defaults.... to...
This shows this information... using these that you can use
chart... defaults.... to...
Usage The total space utilization for l Statistic - l See what the
each file system per hour. The mean total space
data in this chart is presented l Interval - 1 utilization is
differently than the utilization hour for all of your
value shown in the Details tab of file systems.
l Time range -
the file system: l Identify
1 day
l File system utilization is which of your
displayed in GiB. This chart file systems
displays GB. are
consuming
l File system utilization is
the most and
captured once every hour.
least space.
This chart captures one
data point every minute. l Identify
which of your
l There may be temporary
file systems
discrepancies between the
are incurring
file system utilization value
the most and
and the Usage chart. For
least cost.
example, if the usage for a
file system briefly spikes l Use in
during the file system's conjunction
hourly update, the with the
utilization value may information
temporarily appear higher in File
than expected when System
compared to the Usage Usage and
chart. Metering and
receive
notifications
when usage
This shows this information... using these that you can use
chart... defaults.... to...
is not within
expectations.
This shows this information... using these that you can use
chart... defaults.... to...
This shows this information... using these that you can use
chart... defaults.... to...
l Time l Measure
range - impact of
3 hours high
connection
count on file
system and
workload
performance.
l Decide if
additional
mount
targets are
required for
your
workload.
This shows this information... using these that you can use
chart... defaults.... to...
For more information about monitoring metrics and using alarms, see Monitoring Overview.
For information about notifications for alarms, see Notifications Overview.
For more information about monitoring metrics and using alarms, see Monitoring Overview.
For information about notifications for alarms, see Notifications Overview.
To view default metric charts for multiple file systems and mount targets
1. Open the navigation menu. Under Solutions and Platform, go to Monitoring and
click Service Metrics.
2. For Compartment, select the compartment that contains the file storage resource
you're interested in.
3. For Metric Namespace, select oci_filestorage.
The Service Metrics page dynamically updates the page to show charts for each
metric that is emitted by the selected metric namespace.
For more information about monitoring metrics and using alarms, see Monitoring Overview.
For information about notifications for alarms, see Notifications Overview.
1. Export Paths are part of the information contained in an export that makes a file
system available through a mount target. The export path uniquely identifies the file
system within the mount target, letting you associate up to 100 file systems behind a
single mount target. The export path is used by an instance to mount (logically attach
to) the file system. This path is unrelated to any path within the file system or the client
instance. It exists solely as a way to distinguish one file system from another within a
single mount target.
In this mount command example, 10.0.0.6 is the mount target IP
address./FileSystem1 is the unique export path that was specified when the file
system was associated with a mount target during creation.
sudo mount 10.0.0.6:/FileSystem1 /mnt/mountpointA
Important
Warning
Note
See Managing Mount Targets for more information about mount targets and exports.
2. Mount Point Paths are paths within a client instance to a locally accessible directory
to which the remote file system is mounted.
In this mount command example, /mnt/mountpointA is the path to the directory on the
client instance on which the external file system is mounted.
sudo mount 10.0.0.6:/FileSystem1 /mnt/mountpointA
See Mounting File Systems for more information.
3. File System Paths are paths to directories within the file system, and contain the
contents of the file system. When the file system is mounted, you can create any
directory structure within it you like. Snapshots of the file system can be accessed using
the file system path, under the file system's root directory at .snapshot/name.
The following example shows the path to a snapshot called 'January 1' when navigating
from the instance:
/mountpointA/.snapshot/January1
Overview
File Storage service provisioning is fully managed and automatic as your utilization scales.
For more information, see Space Allocation.
Here are the methods you can use to view your file system and snapshot usage:
l The File Storage service reports metered file system utilization and updates hourly. The
metered file system utilization comes from the meteredBytes value in the API, and
represents the authoritative utilization value that is used to count your service cost. You
can access the reported utilization for each of your file systems using the Console, the
Command Line Interface (CLI), or the API. For more information, see the following
section File System Metered Utilization .
l The File Storage service supports Network File System (NFS) protocol, so you can use
the df or du command from your instance command line tool to see usage for mounted
file systems. However, the usage reported by du can differ from both the
meteredBytes value and the df value. For more information, see Using DF and DU
Commands.
Space Allocation
The File Storage service allocates space in blocks of variable size in a way that minimizes
total customer cost and optimizes performance. Other storage systems might allocate blocks
differently than Oracle Cloud Infrastructure File Storage. If you copy files from another
storage device to your Oracle Cloud Infrastructure file system, you might see minor
differences when you compare the physical file size before and after copying.
The File Storage service reports metered utilization size for each file system. The metered
utilization size is updated on an hourly cycle. You can see the metered Utilization size in the
Console on the Details page of the file system. This value comes from the File Storage
service API meteredBytes property which is the total number of bytes consumed by the file
system. The meteredBytes value is updated asynchronously with respect to updates to the
file system. Your usage charges are calculated based on the meteredBytes value.
You can also use the CLI or API to obtain this information. See Managing File Systems for
instructions about how to view your file system utilization.
Important
Snapshot data usage is metered against differentiated data only. If nothing has changed
within the file system since the last snapshot was taken, a new snapshot does not consume
more storage. The metered size of snapshots is included in the reported meteredBytes value
of the file system it belongs to.
For example:
1. Let's say you create a file system called "MyFileSystem" and add "File1". The new file
system now contains 1 GB including metadata. After the hourly update cycle is
complete, the total meteredBytes shown by the File Storage service is 1 GB.
2. Next, you create a snapshot of "MyFileSystem" named "Snapshot1". After the hourly
update cycle is complete, the total meteredBytes shown by the File Storage service
remains at 1 GB, because there's no differentiated data yet.
3. You then overwrite the first 0.5 GB of "File1". Now, "MyFileSystem" has a file that is
different than the version previously captured in "Snapshot1". The meteredBytes value
is 1.5 GB, because the differentiated data between the live file system and the snapshot
is 0.5 GB.
1 GB (snapshot) + 0.5 GB (differentiated data) = 1.5 GB
4. If you then delete "File1". "MyFileSystem" now has a meteredBytes value of 1 GB,
which represents just the usage for "Snapshot1".
5. Finally, delete "Snapshot1". Deleting the snapshot removes its references to the file
data. Provided no other snapshots reference the file data, the space is relinquished and
utilization returns to zero.
Files in the file system require space to be allocated for metadata. 512 bytes are required for
each directory entry, and 8192 bytes are required for each symlink. Multiple hardlinks to a
file create multiple directory entries for the file, and increases the metadata utilization. This
utilization is included in the meteredBytes value of the file system it belongs to.
l df provides the amount of storage metered for your file system. Results are returned
quickly, but can be up to 1 hour out of date.
l du provides the storage used by a directory hierarchy. The du command walks the
directory tree, and if your hierarchy is large, it can take a long time to run and return
results.
l The df command retrieves information provided by the File Storage service using the
NFS FSSTAT call. The NFS FSSTAT call accounts correctly for the way that snapshots
reference file system data. Only utilization caused by differentiated data is reported.
l The du command descends the file system tree and uses each file's size attribute to
total up the space used. When you create a snapshot, it copies the original size attribute
for each file. So, if you run the du command, the snapshot reports the file system's size
at the time the snapshot was taken, not necessarily the snapshot's actual current
utilization.
For example,
1. Let's say you create file system called "MyFileSystem". You then add a 1 GB file called
"FileA" to the file system. Here's how each command would report size.
FileA 1 GB 1 GB
MyFileSystem 1 GB 1 GB
2. You then create "Snapshot1". The snapshot is placed in the /.snapshot folder of
MyFileSystem. Here's how each command would report size:
FileA 1 GB 1 GB
snapshot1 1 GB 0 GB
MyFileSystem 2 GB 1 GB
l df reports 0 GB for Snapshot1 because the data hasn't changed yet, so there is
no space allocated for differentiated data.
l du reports 1 GB for Snapshot1 because it reports the copied file size attribute of
FileA, which is 1 GB.
Important
l df reports the utilization of bytes required by File Storage for metadata and symlinks,
even on empty files.
l du reports empty files as using zero bytes. It doesn't accurately report the bytes being
used by File Storage for metadata and symlinks.
Application Installation
l Application Installation Fails Due to Too Much or Too Little Available Capacity
l Application Performance is Not as Expected
l Apache Webserver Fails
Windows NFS Connections
l Create and Write to File System Fails using Windows NFS
l Mounted Drive is Not Visible in File Explorer
l Mounting from File Explorer Fails With "An Unexpected Error Occurred."
l Access to File System using UNC Path is Slow or Fails
Important
If your application installation is failing because of too little available space, you can expand
the reported available free space. If your application installation is failing because of too
much reported available free space, you can reduce it. Typically, setting the size to 1024 GiB
and the inodes to 1024 GiI permits successful installation.
Important
l Available bandwidth
We recommend that you use bare metal Compute instances because instance bandwidth
scales with the number of oCPU's. Bare metal Compute instances provide the greatest
bandwidth. Virtual machines (VMs) are bandwidth limited based on the number of CPUs
consumed. Single oCPU VM Compute instances provide the least bandwidth.
l Latency
Subnets can be either AD-specific or regional. The type of subnet you choose to create
your File Storage resources in can affect latency. You can create File Storage resources
in either type of subnet.
Regional subnets allow Compute instances to connect to any mount target in the subnet
regardless of AD, with no additional routing configuration. However, to minimize
latency, place mount targets in the same AD as Compute instances just as you would in
an AD-specific subnet.
For more information, see VCNs and Subnets.
Tip
l Mount options
By not providing explicit values for mount options such as rsize and wsize, the client and
server can negotiate the window size for read and write operations that provide the best
performance.
Permission denied: [client IP:port] AH00035: access to /index.php denied (filesystem path '<FSS_mount_
point>/index.php') because search permissions are missing on a component of the path
Additional Information:
Permission checks show sufficient read and execute access on the directory and the files.
Providing full access (777 permission) to the file storage mount point for testing purposes also
fails.
Warning
Cause: By default, the Apache webserver installation expects a local drive. You need to
explicitly direct the installation to NFS.
Or:
Deleting a mount target also deletes all of the exports of associated file systems that exist in
its export set. Data in the file systems is not affected, but the file systems are no longer
available through the deleted mount target. You can create new exports for the file system in
a different mount target and subnet.
2. Note the Compartment and Subnet information of the VCN you want to delete, and to
assist navigation and choosing the correct mount target to delete.
3. Delete the mount target using the following steps:
a. Open the navigation menu. Under Core Infrastructure, click File Storage and
then click Mount Targets.
b. In the List Scope section, select a compartment.
c. Find the mount target you want to delete.
d. Click the Actions icon (three dots), and then click Delete.
Warning
Tip
b. You can use GetMountTarget to verify that the mount target has been deleted. For
example:
GET
/20171215/mountTargets/ocid1.mounttarget.oc1.phx.examplemounttargetid?compartmentId=
<compartmentId>
Host: filestorage.us-phoenix-1.oraclecloud.com
<authorization and other headers>
1. Note the OCID in the error message you receive when you attempt to delete the VCN.
Mount target OCIDs contain the identifier mounttarget. For example:
ocid1.mounttarget.oc1.phx.examplemounttargetid
b. You can use oci fs export get to verify that the mount target has been deleted.
For example:
oci fs export get --export-id ocid1.mounttarget.oc1.phx.examplemounttargetid
The CLI should return a message indicating the mount target is not found. For
example:
{
"code": "NotAuthorizedOrNotFound",
"message": "Authorization failed or requested resource not found.",
"opc-request-id": "<requestID>",
"status": 404
}
If you still can't delete the VCN, be sure there are no other resources remaining in the VCN
that might prevent it. For more information, see Subnet or VCN Deletion.
The export path is specified when you create an export for the file system in a mount target.
It uniquely identifies the file system within the mount target, letting you associate multiple
file systems to a single mount target. The export path is appended to the mount target IP
address, and used to mount the file system.
In this example, 10.0.0.6: is the mount target IP address, and /example/path is the export
path. /mnt/mountpointA is the path to the directory on the client instance on which the
external file system is mounted.
Tip
You can find all the export paths for a file system in the
Exports list shown in its Details page, together with
associated mount target information.
l You can obtain the correct export path by copying mount commands directly from the
file system export. These commands minimize the chance of a typing error. See To get
mount command samples for more information.
l If one file system associated with a mount target uses an export path of '/' , it will
prevent you from associating more file systems with that mount target. No two file
systems associated with the same mount target can have an export path that contains a
complete path of the other.
Possible Cause: There are insufficient unallocated IP addresses in the subnet. The mount
target cannot fail over successfully.
Each mount target requires three internal IP addresses in the subnet to function:
l Two of the IP addresses are used during mount target creation. The third IP address
must remain available for the mount target to use for high availability failover.
l The third IP address is used to create a new VNIC for the mount target during failover.
The original primary IP address is retained.
l The File Storage service doesn't "reserve" the third IP address required for high
availability failover.
l Use care to ensure that enough unallocated IP addresses remain available for your
mount targets to use during failover.
l Do not use /30 or smaller subnets for mount target creation because they do not have
sufficient available IP addresses for mount target creation.
Solution:
Note
Important
For example, open a terminal window on the instance and use the touch command to write a
'helloworld' file:
touch /mnt/yourmountpoint/helloworld
Cause: When a file system is created, the root user owns the root directory. If you're
connecting from an Oracle-provided Linux or CentOS instance, the default user is opc. The
default user is ubuntu when you connect from an Oracle-provided Ubuntu instance. These
default users are not root users, so you can't initially write a file or directory to a new file
system with these users.
l Connect as the root user. Then, create files or directories in the new file system.
l Connect as the root user. Then, change the ownership or permissions of the file system
root directory to allow other users (such as opc or ubuntu) to write to the file system.
l Connect as the root user. Then, create subdirectories with ownership or permissions
that allow other users to write to the subdirectory.
Learn more about updating file and directory ownership and permissions.
l Connect as the default user. Then, use the sudo command to write or to change
permissions or ownership of files or directories. The sudo command temporarily
provides a regular user with root user permissions. Here's an example of using the sudo
command to write to the file system:
sudo touch /mnt/yourmountpoint/helloworld
To enable the command, you must create a security list rule in the subnet containing the
mount target. The rule must be a stateful ingress rule for UDP traffic with a Destination
Port Range of 111.
Click here for instructions about Configuring VCN Security Rules for File Storage.
For more information about this command, see the Linux manual page about showmount.
Important
Snapshots can also break symbolic links that point to a target outside the file system’s root
directory. This is because when you create a snapshot of a file system, it becomes available
as a subdirectory of the .snapshot directory.
To minimize these potential issues, use a relative path as the target path when creating a
symbolic link to a file in the network file system. Also, ensure that relative paths do not point
to a target path outside the File Storage service root directory except when the target is on
the local machine. If you must use a symbolic link that points to a target path outside the file
system, use an absolute path starting with the client’s root directory.
For example:
Important
Symptom: After installing Windows NFS client, you can successfully mount the file system
from Windows, but any attempt to create or update a file in the file system fails.
Cause 1: Registry entries that map the AnonymousGid and AnonymousUid to the root user
are missing or in the wrong place.
Access to NFS file systems requires UNIX-style user and group identities, which are not the
same as Windows user and group identities. To enable users to access NFS shared resources,
Windows client for NFS accesses file systems anonymously, using AnonymousGid and
AnonymousUid. On brand new file systems, write permissions are only granted to the root
user.
Tip
For example:
C:\>mount
fileaccess=755, lang=ANSI
casesensitive=no
sec=sys
following. Replace 10.x.x.x: with the local subnet IP address assigned to your mount
target, fs-export-path with the export path you specified when associating the file
system with the mount target, and X with the drive letter of any available drive you
want to map the file system to.
Tip
umount 10.x.x.x:/fs-export-path X:
Important
9. In the standard Windows Command Line (CMD) window, mount the file system by typing
the following. Replace 10.x.x.x: with the local subnet IP address assigned to your
mount target, fs-export-path with the export path you specified when associating the
file system with the mount target, and X with the drive letter of any available drive you
want to map the file system to.
mount 10.x.x.x:/fs-export-path X:
Cause 2: A standard user is trying to access a file system that was mounted using the
Administrator: Command Prompt (CMD). When mounting file systems, it isn't necessary to
run the Command Prompt as Administrator.
Solution: Unmount the file system and then remount the file system using a standard
Command Prompt. (CMD)
Tip
umount 10.x.x.x:/fs-export-path X:
mount 10.x.x.x:/fs-export-path X:
Important
Symptom: After installing Windows NFS client, you can successfully mount the file system
from Windows, but the file system drive is not visible in File Explorer.
Cause: A standard user is trying to access a file system that was mounted using the
Administrator: Command Prompt (CMD). When mounting file systems, it isn't necessary to
run the Command Prompt as Administrator.
Solution: Unmount the file system and then remount the file system using a standard
Command Prompt. (CMD) See To remount a file system with a standard Command Prompt
(CMD).
Important
Symptom: After installing Windows NFS client, you can successfully mount the file system
from either Windows File Explorer or the Command Prompt (CMD) using mount or net use
commands. However, the file system drive is not visible in PowerShell.
Cause: A known issue exists where drives mapped from outside PowerShell aren't visible
from within PowerShell.
Solution: Unmount the file system and remount the file system within PowerShell, using
options to make it visible in File Explorer and in the CMD application.
by typing the following. Replace 10.x.x.x: with the local subnet IP address assigned to
your mount target, fs-export-path with the export path you specified when
associating the file system with the mount target, and X with the drive letter of any
available drive you want to map the file system to.
Tip
umount 10.x.x.x:/fs-export-path X:
Mounting from File Explorer Fails With "An Unexpected Error Occurred."
Important
Symptom: The IP address and export path are correctly represented in the Folder field.
When you click Finish, the system attempts to connect to the file system, but fails with an
error: "The mapped network drive could not be created because the following error has
occurred: An unexpected error occurred."
Solution 1: Reboot the instance, and mount the file system again using File Explorer.
Overview of Functions
Oracle Functions is a fully managed, multi-tenant, highly scalable, on-demand, Functions-as-
a-Service platform. It is built on enterprise-grade Oracle Cloud Infrastructure and powered by
the Fn Project open source engine. Use Oracle Functions (sometimes abbreviated to just
Functions) when you want to focus on writing code to meet business needs.
The serverless and elastic architecture of Oracle Functions means there's no infrastructure
administration or software administration for you to perform. You don't provision or maintain
compute instances, and operating system software patches and upgrades are applied
automatically. Oracle Functions simply ensures your app is highly-available, scalable, secure,
and monitored. With Oracle Functions, you can write code in Java, Python, Node, Go, and
Ruby (and for advanced use cases, bring your own Dockerfile, and Graal VM). You can then
deploy your code, call it directly or trigger it in response to events, and get billed only for the
resources consumed during the execution.
You can access Oracle Functions using the Console, a CLI, and a REST API. You can invoke the
functions you deploy to Oracle Functions using the CLI or by making signed HTTP requests.
Oracle Functions is integrated with Oracle Cloud Infrastructure Identity and Access
Management (IAM), which provides easy authentication with native Oracle Cloud
Infrastructure identity functionality. See Overview of Oracle Cloud Infrastructure Identity and
Access Management.
To get set up and running quickly with Oracle Functions, see the Quick Start Guides.
For general information about using the REST API, see REST APIs.
l applications
l functions
You can also have events in other services invoke functions in Oracle Functions. See Invoking
Oracle Functions from Other Oracle Cloud Infrastructure Services.
Resource Identifiers
Most types of Oracle Cloud Infrastructure resources have a unique, Oracle-assigned identifier
called an Oracle Cloud ID (OCID). For information about the OCID format and other ways to
identify your resources, see Resource Identifiers.
An administrator in your organization needs to set up groups, compartments, and policies that
control which users can access which services, which resources, and the type of access. For
example, the policies control who can create new users, create and manage the cloud
network, launch instances, create buckets, download objects, etc. For more information, see
Getting Started with Policies. For specific details about writing policies for each of the
different services, see Policy Reference.
If you’re a regular user (not an administrator) who needs to use the Oracle Cloud
Infrastructure resources that your company owns, contact your administrator to set up a user
ID for you. The administrator can confirm which compartment or compartments you should be
using.
l 10 applications
l 20 functions
See Service Limits for a list of applicable limits and instructions for requesting a limit
increase.
The maximum amount of data you can send to a function (the function's request payload) is
6MB. The maximum amount of data a function can return in response to a request (the
function's response payload) is 6MB. These limits are fixed and cannot be changed.
Some other Oracle Functions capabilities and limits are also fixed. However, there are also a
number that you can change. See Changing Oracle Functions Default Behavior.
Functions Developers
Oracle Cloud Infrastructure users who use Oracle Functions to create and deploy functions are
referred to as 'functions developers'. To use Oracle Functions, functions developers must
have Oracle Cloud Infrastructure user accounts. Their user accounts must belong to groups to
which appropriate policies grant access to function-related resources.
See Create Groups and Users to use with Oracle Functions, if they don't exist already.
Applications
In Oracle Functions, an application is:
the application
l a way to ensure function runtime isolation
When you define an application in Oracle Functions, you specify the subnets in which to run
the functions in the application.
When functions from different applications are invoked simultaneously, Oracle Functions
ensures these function executions are isolated from each other.
Functions
In Oracle Functions, functions are:
l small but powerful blocks of code that generally do one simple thing
l grouped into applications
l stored as Docker images in a specified Docker registry
l invoked in response to a CLI command or signed HTTP request
When you deploy a function to Oracle Functions using the Fn Project CLI, the function is built
as a Docker image and pushed to a specified Docker registry.
A definition of the function is stored as metadata in the Oracle Functions server. The definition
describes how the function is to be executed and includes:
Oracle Functions shows functions, and the applications into which they are grouped, in the
Console.
Invocations
In Oracle Functions, a function's code is run (or executed) when the function is called (or
invoked). You can invoke a function that you've deployed to Oracle Functions from:
When a function is invoked for the first time, Oracle Functions pulls the function's Docker
image from the specified Docker registry, runs it as a Docker container, and executes the
function. If there are subsequent requests to the same function, Oracle Functions directs
those requests to the same container. After a period being idle, the Docker container is
removed.
Triggers
A trigger is the result of an action elsewhere in the system, that sends a request to invoke a
function in Oracle Functions. For example, an event in the Events service might cause a
trigger to send a request to Oracle Functions to invoke a function. Alternatively, a trigger
might send regular requests to invoke a function on a defined, time-based schedule.
A function might not be associated with any triggers, or it can be associated with one or
multiple triggers.
The above process of deploying a function to Oracle Functions is shown in the diagram.
When a function is invoked for the first time, Oracle Functions first verifies the request with
the IAM service. Assuming the request passes authentication and authorization checks, Oracle
Functions then passes the request to the Fn Server, which uses the function definition to:
l identify the Docker image of the function to pull from the Docker registry
l execute the function by running the function's image as a container on an instance in a
subnet associated with the application to which the function belongs
When the function is executing inside the container, the function can read from and write to
other resources and services running in the same subnet (for example, Database as a
Service). The function can also read from and write to other shared resources (for example,
Object Storage), and other Oracle Cloud Services. You can specify the maximum length of
time the function is allowed to execute by setting a timeout in the func.yaml file or in the
Console.
Oracle Functions stores the function's logs in Oracle Cloud Infrastructure or in an external
logging destination.
When the function has finished executing and after a period being idle, the Docker container is
removed. If Oracle Functions receives another call to the same function before the container
is removed, the second request is routed to the same running container. If Oracle Functions
receives a call to a function that is currently executing inside a running container, Oracle
Functions scales horizontally to serve both incoming requests and a second Docker container
is started.
For resiliency and high availability, both the control plane and data plane components are
distributed across different availability domains and fault domains in a region. If one of the
domains ceases to be available, the components in the remaining domains take over to
ensure that function definition management and execution are not disrupted.
When functions are invoked, they run in the subnets specified for the application to which the
functions belong. For resiliency and high availability, best practice is to specify a regional
subnet for an application (or alternatively, multiple AD-specific subnets in different
availability domains). If an availability domain specified for an application ceases to be
available, Oracle Functions runs functions in an alternative availability domain.
In the case of Functions, when a function is invoked for the first time, the function's image is
run as a container on an instance in a subnet associated with the application to which the
function belongs. When the function is executing inside the container, the function can read
from and write to other shared resources and services running in the same subnet (for
example, Database as a Service). The function can also read from and write to other shared
resources (for example, Object Storage), and other Oracle Cloud Services.
If Oracle Functions receives multiple calls to a function that is currently executing inside a
running container, Oracle Functions automatically and seamlessly scales horizontally to serve
all the incoming requests. Oracle Functions starts multiple Docker containers, up to the limit
specified for your tenancy. The default limit is 30 GB of RAM reserved for function execution
per availability domain, although you can request an increase to this limit. Provided the limit
is not exceeded, there is no difference in response time (latency) between functions executing
on the different containers.
When functions from different applications are invoked simultaneously, Oracle Functions
ensures these function executions are isolated from each other.
l A tenancy administrator must have configured your Oracle Cloud Infrastructure tenancy
for function development. There are a number of different tenancy configuration tasks
to complete. For more information, see Configuring Your Tenancy for Function
Development.
When your tenancy is configured, you will have access, via a suitable policy and user
account, to a compartment that has a VCN with at least one public subnet (and an
internet gateway) or at least one private subnet (and a service gateway). For more
information about these network components, see Overview of Networking.
You will also have access to a Docker registry in which to store images. This
documentation assumes you will be using Oracle Cloud Infrastructure Registry as your
Docker registry and provides instructions accordingly. For more information, see
Overview of Registry .
l You must have configured your client environment for functions development. There are
a number of different client environment configuration tasks to complete. For more
information, see Configuring Your Client Environment for Function Development.
To get set up and running quickly with Oracle Functions, see the Quick Start Guides.
Availability by Region
Oracle Functions is available in the Oracle Cloud Infrastructure regions listed at Regions and
Availability Domains. Refer to that topic to see region identifiers, region keys, and availability
domain names.
When a tenancy is created, an Administrators group is automatically created for the tenancy.
Users that are members of the Administrators group can perform any operation on resources
in the tenancy. Oracle Functions users are typically not members of the Administrators group,
and do not have to be. However, a member of the Administrators group does need to perform
a number of administrative tasks to enable users to use Oracle Functions.
To set up your tenancy for function development, you have to complete the following tasks in
the order shown in this checklist (the instructions in the topics below assume that you are a
tenancy administrator):
1 Create Groups and Users to use with Oracle Functions, if they don't
exist already
3 Create the VCN and Subnets to Use with Oracle Functions, if they
don't exist already
When you have set up your tenancy for function development, the next step is to set up your
client development environment (see Configuring Your Client Environment for Function
Development).
Create Groups and Users to use with Oracle Functions, if they don't exist already
Before users can start using Oracle Functions to create and deploy functions, as a tenancy
administrator you have to create Oracle Cloud Infrastructure user accounts, along with a
group to which the user accounts belong. Later on, you'll define policies to give the group (and
the user accounts that belong to it) access to function-related resources. If a suitable group
and user accounts already exist, there's no need to create new ones.
Before users can start using Oracle Functions to create and deploy functions, as a tenancy
administrator you have to create:
l a compartment to own network resources (a VCN, a public or private subnet, and other
resources such as an internet gateway or service gateway, a route table, security lists)
l a compartment to own function-related resources (functions, applications)
Note that the same compartment can own both network resources and function-related
resources. Alternatively, you can create two separate compartments for network resources
and function-related resources.
Create the VCN and Subnets to Use with Oracle Functions, if they don't exist
already
Before users can start using Oracle Functions to create and deploy functions, a VCN containing
the subnets in which to create functions and applications must already exist. The VCN can be,
but need not be, owned by the same compartment to which other function-related resources
will belong.
Each subnet in the VCN must have a CIDR block that provides at least a certain minimum
number of free IP addresses, as follows:
Note that Oracle strongly recommends each subnet has a CIDR block that provides more than
the minimum number of free IP addresses.
To support the largest possible number of concurrent connections, Oracle also strongly
recommends that the security lists used by subnets in the VCN only have stateless rules.
If you do decide to create a new VCN, you have several options, including the following:
l You can create the new VCN and have related resources created automatically at the
same time, using one of the VCN wizards. For example, this topic describes how to use
the VCN with Internet Connectivity wizard to create a VCN. As well as creating the
VCN, the VCN with Internet Connectivity wizard creates a public regional subnet
and a private regional subnet, along with an internet gateway, a NAT gateway, and a
service gateway. The VCN with Internet Connectivity wizard also creates route
tables and security lists. For more information about the VCN wizards, see Virtual
Networking Quickstart.
l You can create just the VCN initially, and then create the related resources yourself
later (see VCNs and Subnets). In this case, you can choose which of the following to
create:
o Public subnets and an internet gateway (see Internet Gateway). In this case, a
route table must include a route rule that targets the internet gateway, with its
Destination CIDR Block property set to 0.0.0.0/0.
o Private subnets and a service gateway (see Access to Oracle Services: Service
Gateway). In this case, the service gateway must be set up to allow access to All
<region> Services In Oracle Services Network. A route table must include
a route rule that targets the service gateway, with its Destination Service
property set to All <region> Services In Oracle Services Network.
For example, if you don't want to expose traffic over the public internet, create private
subnets and a service gateway (see Oracle Functions Support for Private Network
Access).
Note that to use an external logging destination like Papertrail, you have to create a VCN with
public subnets (see Storing and Viewing Function Logs).
To create a VCN to use with Oracle Functions, using the VCN with Internet Connectivity
wizard to create related resources automatically:
3. Choose the compartment that will own the network resources (on the left side of the
page). For example, acme-network.
The VCN can be, but need not be, owned by the same compartment to which other
function-related resources will belong. The page updates to display only the resources
in that compartment.
4. Click Start VCN Wizard to create a new VCN.
5. In the Start VCN Wizard dialog box, select VCN with Internet Connectivity and
click Start VCN Wizard.
Note that the following instructions assume that you select the VCN with Internet
Connectivity wizard to create the VCN and related resources automatically. However,
if a different VCN wizard is a better fit for your requirements, select that wizard instead
and configure it appropriately (see Virtual Networking Quickstart).
6. On the Configuration page, enter:
l Name: A meaningful name for the cloud network, such as acme-functions-vcn.
The name doesn't have to be unique, but it cannot be changed later in the
Console. Avoid entering confidential information.
l Compartment: The compartment that will own the network resources (by
default, the compartment you selected earlier is shown). For example, acme-
network.
l VCN CIDR Block, Public Subnet CIDR Block, and Private Subnet CIDR
Block: CIDR blocks for the VCN, and the public and private regional subnets. The
CIDR blocks you specify for the regional subnets must not overlap, and must have
a minimum of 32 free IP addresses.
l Use DNS Hostnames in this VCN: Select this option.
7. Click Next and on the Review and Create page, verify the details of the VCN and
related resources that will be created.
8. Click Create to create the VCN, along with the related resources.
9. Click View Virtual Cloud Network to see details of the VCN and the related resources
that have been created.
Before users can start using Oracle Functions to create and deploy functions, as a tenancy
administrator you have to create a number of Oracle Cloud Infrastructure policies to grant
access to function-related and network resources. You have to:
l Create a Policy to Give Oracle Functions Users Access to Oracle Cloud Infrastructure
Registry Repositories
l Create a Policy to Give Oracle Functions Users Access to Function-Related Resources
l Create a Policy to Give Oracle Functions Users Access to Network Resources
l Create a Policy to Give the Oracle Functions Service Access to Network Resources
l Create a Policy to Give the Oracle Functions Service Access to Repositories in Oracle
Cloud Infrastructure Registry
Oracle Functions Root Allow service FaaS Create a Policy to Give the
service access to compartment to use virtual- Oracle Functions Service
network resources network-family in Access to Network
compartment Resources
<compartment-name>
Oracle Functions Root Allow service FaaS Create a Policy to Give the
service access to compartment to read repos in Oracle Functions Service
repositories in tenancy Access to Repositories in
Oracle Cloud Oracle Cloud
Infrastructure Infrastructure Registry
Registry
CREATE A POLICY TO GIVE ORACLE FUNCTIONS USERS ACCESS TO ORACLE CLOUD I NFRASTRUCTURE
REGISTRY REPOSITORIES
When Oracle Functions users work with functions, they have to access repositories in Oracle
Cloud Infrastructure Registry. Users can only access repositories that the groups to which
they belong have been granted access. To enable users to access a repository, you must
create an identity policy to grant the groups access to that repository.
To create a policy to give Oracle Functions users access to repositories in Oracle Cloud
Infrastructure Registry:
1. Log in to the Console as a tenancy administrator and create a new policy in the root
compartment:
a. Open the navigation menu. Under Governance and Administration, go to
Identity and click Policies.
b. Follow the instructions in To create a policy, and give the policy a name (for
example, acme-functions-developers-ocir-access).
2. Specify a policy statement to enable the group to obtain the auto-generated Object
Storage namespace string of the tenancy (required to log in to Oracle Cloud
Infrastructure Registry):
Allow group <group-name> to read objectstorage-namespaces in tenancy
where <group-name> is the name of the group to which users using Oracle Functions
belong.
For example:
Allow group acme-functions-developers to read objectstorage-namespaces in tenancy
The above policy statement also provides access to function logs stored in a storage
bucket in Oracle Cloud Infrastructure Object Storage (see Storing and Viewing Function
Logs).
3. Specify a policy statement to give the group access to repositories in Oracle Cloud
Infrastructure Registry:
Allow group <group-name> to manage repos in tenancy
where <group-name> is the name of the group to which users using Oracle Functions
belong.
For example:
Allow group acme-functions-developers to manage repos in tenancy
The above policy statement gives the group permission to manage all repositories in the
tenancy. If you consider this to be too permissive, then you can restrict the repositories
to which the group has access by including a where clause in the manage repos
statement. Note that if you do include a where clause, you must also include a second
statement in the policy to enable the group to inspect all repositories in the tenancy
(when using the Console).
For example, the following policy statements restrict the group to accessing only
repositories with names that start 'acme-web-app', but also enables the group to
inspect all repositories in the tenancy:
Allow group acme-functions-developers to inspect repos in tenancy
4. Click Create.
When Oracle Functions users create functions and applications, they have to specify a
compartment for those function-related resources (including for metrics emitted by Oracle
Functions). Users can only specify a compartment that the groups to which they belong have
been granted access. To enable users to specify a compartment, you must create an identity
policy to grant the groups access to that compartment.
To create a policy to give Oracle Functions users access to function-related resources in the
compartment that will own those resources:
1. Log in to the Console as a tenancy administrator and create a new policy in the
compartment that will own Oracle Functions resources:
a. Open the navigation menu. Under Governance and Administration, go to
Identity and click Policies.
b. Follow the instructions in To create a policy, and give the policy a name (for
example, acme-functions-developers-manage-access).
2. Specify a policy statement to give the group access to all function-related resources in
the compartment:
Allow group <group-name> to manage functions-family in compartment <compartment-name>
For example:
Allow group acme-functions-developers to manage functions-family in compartment acme-functions-
compartment
3. Specify a second policy statement to give the group access to metrics emitted by Oracle
Functions:
Allow group <group-name> to read metrics in compartment <compartment-name>
For example:
4. Click Create.
When Oracle Functions users create a function or application, they have to specify a VCN and
a subnet in which to create them. Users can only specify VCNs and subnets in compartments
that the groups to which they belong have been granted access. To enable users to specify a
VCN and subnet, you must create an identity policy to grant the groups access to the
compartment.
1. Log in to the Console as a tenancy administrator and create a new policy in the
compartment that will own network resources:
a. Open the navigation menu. Under Governance and Administration, go to
Identity and click Policies.
b. Follow the instructions in To create a policy, and give the policy a name (for
example, acme-functions-developers-manage-network-access).
2. Specify a policy statement to give the group access to the network resources in the
compartment:
Allow group <group-name> to use virtual-network-family in compartment <compartment-name>
For example:
Allow group acme-functions-developers to use virtual-network-family in compartment acme-network
3. Click Create.
CREATE A POLICY TO GIVE THE ORACLE FUNCTIONS S ERVICE ACCESS TO NETWORK RESOURCES
When Oracle Functions users create a function or application, they have to specify a VCN and
a subnet in which to create them. To enable the Oracle Functions service to create the function
or application in the specified VCN and subnet, you must create an identity policy to grant the
Oracle Functions service access to the compartment to which the network resources belong.
To create a policy to give the Oracle Functions service access to network resources:
For example:
Allow service FaaS to use virtual-network-family in compartment acme-network
3. Click Create.
CREATE A POLICY TO GIVE THE ORACLE FUNCTIONS S ERVICE ACCESS TO REPOSITORIES IN ORACLE CLOUD
I NFRASTRUCTURE REGISTRY
The Oracle Functions service must have read access to images stored for functions in
repositories in Oracle Cloud Infrastructure Registry. To enable the Oracle Functions service to
access repositories in Oracle Cloud Infrastructure Registry, you must create an identity
policy.
To create a policy to give the Oracle Functions service access to repositories in Oracle Cloud
Infrastructure Registry:
The above policy statement gives the Oracle Functions service access to all
repositories in the tenancy. If you consider this to be too permissive, then you can
restrict the repositories to which Oracle Functions has access by including a where
clause in the read repos statement.
For example, the following policy statement restricts Oracle Functions to
accessing only repositories with names that start 'acme-web-app':
Allow service FaaS to read repos in tenancy where all {target.repo.name=/acme-web-app*/ }
3. Click Create.
When setting up your Oracle Functions development environment, you have different options:
l Option 1: Setting up Cloud Shell. (Recommended) For users trying out Oracle
Functions for the first time, this is the recommended way to get started quickly. By
copying and pasting a few commands from the Console into the Cloud Shell window, you
can set up an Oracle Functions development environment in just a few minutes.
This option enables you to experiment creating, deploying, and invoking new functions.
You can also explore Oracle Functions using the samples on Git Hub (see Oracle
Functions Samples). If you want to set up Cloud Shell as your Oracle Functions
development environment, see the instructions in the Oracle Functions on Cloud
Shell Quick Start Guide.
l Option 2: Setting up a local machine. For most users (especially Mac and Linux
users), this will be the way to work with Oracle Functions. If you set up a local machine,
you'll have to specify --provider oracle when you create a new Fn Project CLI
context.
This option enables Oracle Functions to perform authentication and authorization using
Oracle Cloud Infrastructure request signing, private keys, user groups, and policies that
grant permissions to those user groups.
This documentation assumes you want to set up a local machine as your client
environment, and provides instructions accordingly (see Setting up a Local Machine as a
Development Environment). Instructions for setting up a local machine are also
included in the Oracle Functions in a Local Dev Environment Quick Start Guide.
l Option 3: Setting up an Oracle Cloud Infrastructure compute instance. For
some users, this will be more convenient than setting up a local machine. If you set up
an Oracle Cloud Infrastructure compute instance, you'll have to specify --provider
oracle-ip when you create a new Fn Project CLI context.
This option enables Oracle Functions to perform authentication and authorization using
instance OCIDs, dynamic groups, and policies granting permissions to those dynamic
groups. This approach removes the requirement for users to manage private keys. Note
that to set up an Oracle Functions development environment on an Oracle Cloud
Infrastructure compute instance, you must:
o have permission to create dynamic groups
o create a new dynamic group that includes the compute instance's OCID
o create a policy to give the new dynamic group access to function resources,
network resources, and Oracle Cloud Infrastructure Registry
o specify --provider oracle-ip when you create a new Fn Project CLI context
If you want to set up an Oracle Cloud Infrastructure compute instance as your Oracle
Functions development environment, see the instructions in the Oracle Functions on an
OCI Compute Instance Quick Start Guide.
To set up a local machine as your client environment for function development, you have to
complete the following tasks in the order shown in this checklist:
7 7. Set the Context for the Fn Project CLI Using the oracle.profile
Parameter
9 9. Start Docker
Click each of the links in the checklist in turn, and follow the instructions.
When you have completed all of the development environment configuration tasks, confirm
your configuration is correct (see Verifying Your Configuration for Function Development).
1. Set up an Oracle Cloud Infrastructure API Signing Key for Use with Oracle
Functions
Before using Oracle Functions, you have to set up an Oracle Cloud Infrastructure API signing
key.
For more information and other options, see Required Keys and OCIDs.
The instructions below describe how to create a new ~/.oci directory, how to generate a new
private key file and public key file in that ~/.oci directory, how to upload the public key to
Oracle Cloud Infrastructure to create a new API signing key, and how to obtain a fingerprint
for the public API key. Be aware that instructions and examples elsewhere in this
documentation assume the ~/.oci directory exists and contains the private and public key
files.
If your user account already has an API signing key, create the ~/.oci directory if it doesn't
exist, and then go straight to 2. Create a Profile in the Oracle Cloud Infrastructure
CLI Configuration File.
If your user account doesn't already have an API signing key, follow the steps below, but note
the following:
l If you already have a private key file and public key file but they are not in the ~/.oci
directory, and you know the passphrase that was used to encrypt the existing private
key file, there's no need to create new private and public key files. Having created the
~/.oci directory if it doesn't exist, go straight to the step below that instructs you to
create a new API signing key and upload the public key value to Oracle Cloud
Infrastructure to obtain a fingerprint.
3. Assuming the ~/.oci directory does not already exist, create it. For example, by
entering:
mkdir ~/.oci
4. Generate a private key encrypted with a passphrase that you provide by entering:
$ openssl genrsa -out ~/.oci/<private-key-file-name>.pem -aes128 2048
where <private-key-file-name> is a name of your choice for the private key file (for
example, john_api_key_private.pem).
For example:
$ openssl genrsa -out ~/.oci/john_api_key_private.pem -aes128 2048
5. When prompted, enter a passphrase to encrypt the private key file. Be sure to make a
note of the passphrase you enter, as you will need it later.
6. When prompted, re-enter the passphrase to confirm it.
7. Confirm that the private key file has been created in the directory you specified. For
example, by entering:
$ ls -l ~/.oci/john_api_key_private.pem
8. Change permissions on the file to ensure that only you can read it. For example, by
entering:
$ chmod go-rwx ~/.oci/john_api_key_private.pem
9. Generate a public key (in the same location as the private key file) by entering:
$ openssl rsa -pubout -in ~/.oci/<private-key-file-name>.pem -out ~/.oci/<public-key-file-
name>.pem
where:
l <private-key-file-name> is what you specified earlier as the name of the
private key file (for example, john_api_key_private.pem)
l <public-key-file-name> is a name of your choice for the public key file (for
example, john_api_key_public.pem)
For example:
$ openssl rsa -pubout -in ~/.oci/john_api_key_private.pem -out ~/.oci/john_api_key_public.pem
10. When prompted, enter the same passphrase you previously entered to encrypt the
private key file.
11. Confirm that the public key file has been created in the directory you specified. For
example, by entering:
$ ls -l ~/.oci/
12. Copy the contents of the public key file you just created. For example, by entering:
13. Having created the API key pair, upload the public key value to Oracle Cloud
Infrastructure:
a. Log in to the Console as the Oracle Cloud Infrastructure user who will be using
Oracle Functions to create and deploy functions.
b. In the top-right corner of the Console, open the Profile menu ( ) and then click
User Settings to view the details.
c. On the API Keys page, click Add Public Key.
d. Paste the public key's value into the window and click Add.
The key is uploaded and its fingerprint is displayed (for example,
d1:b2:32:53:d3:5f:cf:68:2d:6f:8b:5f:77:8f:07:13).
e. (Optional) Note the fingerprint value. You'll use the fingerprint in a subsequent
configuration task, so you might want to copy it to a convenient and secure
location.
When you have completed the steps in this topic, go on to 2. Create a Profile in the Oracle
Cloud Infrastructure CLI Configuration File.
Before using Oracle Functions, you must have an Oracle Cloud Infrastructure CLI
configuration file that contains the credentials of the user account that you will be using to
create and deploy functions. These user account credentials are referred to as a 'profile'.
The Oracle Cloud Infrastructure CLI configuration file can contain several profiles. If you
already have a configuration file containing one or more profiles, you have to add a new
profile to the existing file for the Oracle Cloud Infrastructure user who will be using Oracle
Functions to create and deploy functions
To create a profile in the Oracle Cloud Infrastructure CLI configuration file for the user
account that you will be using to create and deploy functions:
3. Do one of the following, depending on whether the ~/.oci directory already contains a
file called config:
l If the ~/.oci directory already contains a file called config, open the file in a text
editor.
l If the ~/.oci directory doesn't yet contain a file called config, create the file and
open it in a text editor. For example, by entering:
$ vim ~/.oci/config
where:
When you have completed the steps in this topic, go on to 3. Create and Configure a Copy of
oci-curl.
You can use a bash script provided by Oracle (commonly referred to as oci-curl) to invoke a
function. The oci-curl script creates a signed request, based on credentials you provide in the
body of the script. For more information about oci-curl, see Request Signatures - Bash.
To use oci-curl to invoke a function, you must provide the credentials of an Oracle Cloud
Infrastructure user that has been granted access to resources in the same tenancy and
belonging to the same compartment as the function (see Create Policies to Control Access to
Network and Function-Related Resources).
Typically you'll want to invoke a function as the functions developer that's configured for your
development environment. The instructions below assume that is the case.
The instructions in this topic assume you have already completed the steps in 2. Create a
Profile in the Oracle Cloud Infrastructure CLI Configuration File.
$ mkdir oci-curl
$ vim ~/oci-curl/oci-curl.sh
The name and location of the new file is up to you, but the following instructions
assume ~/oci-curl/oci-curl.sh.
d. Paste the oci-curl script code that you copied earlier into the new file.
e. Save the file but leave it open so you can add your credentials.
3. Replace the sample credentials in the oci-curl.sh file with those of the user account that
you want to invoke functions, as follows:
a. Locate the following lines in the oci-curl.sh file that contain sample credential
values:
# TODO: update these values to your own
local tenancyId="ocid1.tenancy.oc1..aaaaaaaab______dsq";
local authUserId="ocid1.user.oc1..aaaaaaaas______o3r";
local keyFingerprint="20:3b:97:13:55:1c:5b:0d:d3:37:d8:50:4e:c5:3a:34";
local privateKeyPath="/Users/someuser/.oci/oci_api_key.pem";
Tip
b. Change the value of the tenancyId parameter in the oci-curl.sh file by replacing
the sample value in quotes with the OCID of the tenancy in which the function has
been deployed. For example:
local tenancyID="ocid1.tenancy.oc1..aaaaaaaap______keq";
c. Change the value of the authUserID parameter in the oci-curl.sh file by replacing
the sample value in quotes with the OCID of the user account that you want to run
the function. The user account must have access to resources in the same tenancy
and belonging to the same compartment as the function. For example:
local authUserId="ocid1.user.oc1..aaaaaaaas______7ap";
local keyFingerprint="d1:b2:32:53:d3:5f:cf:68:2d:6f:8b:5f:77:8f:07:";
Note
When you have completed the steps in this topic, go on to 4. Install Docker for Use with
Oracle Functions.
Before using Oracle Functions, a version of Docker supported by Fn Project must be installed
in your development environment. If Docker is not already installed, or the installed version
of Docker is not supported, you'll have to install or upgrade Docker.
The instructions in this topic assume you have already completed the steps in 3. Create and
Configure a Copy of oci-curl.
l If you see an error message indicating that Docker is not installed, you have to
install Docker before proceeding to the next step. See the Docker documentation
for information about installing Docker on your platform. If your platform is
Oracle Linux, see Oracle Container Runtime for Docker User's Guide.
l If you see a message indicating the version of Docker that's installed, go to the
next step.
4. Assuming Docker is installed, go to the Fn Project home page on GitHub to confirm that
the installed version of Docker is at least the minimum version specified in the Pre-
requisites section.
If the installed version of Docker is not supported by Fn Project, you have to upgrade
the version of Docker before proceeding. See the Docker documentation for information
about upgrading Docker on your platform. If your platform is Oracle Linux, see Oracle
Container Runtime for Docker User's Guide.
When you have completed the steps in this topic, go on to 5. Install the Fn Project CLI.
Before using Oracle Functions, the Fn Project CLI must be installed in your development
environment.
You can install the Fn Project CLI in a number of different ways according to your
environment.
The instructions in this topic assume you have already completed the steps in 4. Install
Docker for Use with Oracle Functions.
Assuming the Fn Project CLI has been installed correctly, you'll see a message
indicating the version of the CLI that has been installed.
When you have completed the steps in this topic, go on to 6. Create an Fn Project CLI Context
to Connect to Oracle Cloud Infrastructure.
Before using Oracle Functions, you have to configure the Fn Project CLI to connect to your
Oracle Cloud Infrastructure tenancy.
When the Fn Project CLI is initially installed, it's configured for a local development 'context'.
To configure Fn Project CLI to connect to your Oracle Cloud Infrastructure tenancy instead,
you have to create a new context. The context specifies Oracle Functions endpoints, the
OCID of the compartment to which deployed functions will belong, and the address of the
Docker registry to and from which to push and pull images.
You can define multiple contexts, each stored in a different context file in .yaml format. By
default, the individual context files are stored in the ~/.fn/contexts directory. The
~/.fn/config.yaml file specifies which context file Fn Project uses.
To create a new context, you can create a new context file manually and edit the
~/.fn/config.yaml file by hand to point to that file. Alternatively, you can use the Fn Project
CLI to interactively create the new context file and instruct the Fn Project CLI to start using
that file, as described below.
The instructions in this topic assume you have already completed the steps in 5. Install the Fn
Project CLI.
3. Specify that the Fn Project CLI is to use the new context by entering:
$ fn use context <my-context>
where <my-context> is the name you specified in the previous step. For example:
$ fn use context johns-oci-context
4. Configure the new context with the OCID of the compartment that you want to own the
deployed functions (you might have created a new compartment specifically for this
purpose, see Create Compartments to Own Network Resources and Oracle Functions
Resources in the Tenancy, if they don't exist already) by entering:
$ fn update context oracle.compartment-id <compartment-ocid>
For example:
$ fn update context oracle.compartment-id ocid1.compartment.oc1..aaaaaaaarvdfa72n...
5. Configure the new context with the api-url endpoint to use when calling the API by
entering:
$ fn update context api-url <api-endpoint>
6. Configure the new context with the address of the Docker registry that you want to use
with Oracle Functions by entering:
$ fn update context registry <region-key>.ocir.io/<tenancy-namespace>/<repo-name>
where:
l <region-key> is the key of the Oracle Cloud Infrastructure Registry region. For
example, phx for Phoenix. See Availability by Region.
Oracle recommends that the Docker registry you specify is in the same region as
the subnet on which you intend functions to run.
l <tenancy-namespace> is the auto-generated Object Storage namespace string of
the tenancy in which to create repositories (as shown on the Tenancy
Information page). For example, the namespace of the acme-dev tenancy might
be ansh81vru1zp. Note that for some older tenancies, the namespace string
might be the same as the tenancy name in all lower-case letters (for example,
acme-dev).
l <repo-name> is a repository name to pre-pend to the names of functions that you
deploy.
For example:
$ fn update context registry phx.ocir.io/ansh81vru1zp/acme-repo
7. (Optional) Verify the Fn Project CLI context you've created by viewing the context file.
For example, by entering:
$ more ~/.fn/contexts/johns-oci-context.yaml
api-url: https://functions.us-phoenix-1.oci.oraclecloud.com
provider: oracle
registry: phx.ocir.io/ansh81vru1zp/acme-repo
When you have completed the steps in this topic, go on to 7. Set the Context for the Fn Project
CLI Using the oracle.profile Parameter.
7. Set the Context for the Fn Project CLI Using the oracle.profile Parameter
Before using Oracle Functions, you have to configure the Fn Project CLI to use the new profile
you added to the Oracle Cloud Infrastructure CLI configuration file ~/.oci/config (see 2.
Create a Profile in the Oracle Cloud Infrastructure CLI Configuration File). The profile you
added contains the credentials of the user account you'll be using to create and deploy
functions.
Note that unless you specify otherwise, the Fn Project CLI will attempt to use a profile in the
~/.oci/config file named default.
The instructions in this topic assume you have already completed the steps in 6. Create an Fn
Project CLI Context to Connect to Oracle Cloud Infrastructure.
To configure the Fn Project CLI to use the profile you've created for use with Oracle Functions:
For example:
$ fn update context oracle.profile john-oci-profile
When you have completed the steps in this topic, go on to 8. Generate an Auth Token to
Enable Login to Oracle Cloud Infrastructure Registry.
Before using Oracle Functions, the user account you'll be using to create and deploy functions
must have an Oracle Cloud Infrastructure auth token. You use the auth token as the password
when logging Docker in to Oracle Cloud Infrastructure Registry
The instructions in this topic assume you have already completed the steps in 7. Set the
Context for the Fn Project CLI Using the oracle.profile Parameter.
If the user account already has an auth token, go straight on to 9. Start Docker. Otherwise, if
the user account does not have an auth token, generate an auth token now.
To generate an auth token for the user account you'll be using to create and deploy functions:
When you have completed the steps in this topic, go on to 9. Start Docker.
9. Start Docker
Before using Oracle Functions, Docker must be running in your development environment. If
it is not running, you must start Docker before proceeding.
The instructions in this topic assume you have already completed the steps in 8. Generate an
Auth Token to Enable Login to Oracle Cloud Infrastructure Registry.
When you have completed the steps in this topic, go on to 10. Log in to Oracle Cloud
Infrastructure Registry.
Before using Oracle Functions, you have to log Docker in to the Docker registry in which you
are going to store your functions as Docker images. This is the Docker registry specified in the
Fn Project CLI context (see 6. Create an Fn Project CLI Context to Connect to Oracle Cloud
Infrastructure).
You can store functions in public and private repositories in Oracle Cloud Infrastructure
Registry, an Oracle-managed registry built on top of Oracle Cloud Infrastructure.
When you log Docker into a Docker registry, you have to provide the appropriate
authentication details. For example, in the case of Oracle Cloud Infrastructure Registry, you
have to provide the tenancy Object Storage namespace, the user name, and the user's auth
token.
The instructions in this topic assume you have already completed the steps in 9. Start Docker.
where <region-key> is the key for the Oracle Cloud Infrastructure Registry region
specified in the Fn Project CLI context (see 6. Create an Fn Project CLI Context to
Connect to Oracle Cloud Infrastructure). For example, phx for Phoenix. See Availability
by Region.
For example:
$ docker login phx.ocir.io
3. When prompted for Username, enter the name of the user you will be using with
Oracle Functions to create and deploy functions, in the format:
<tenancy-namespace>/<username>
where <tenancy-namespace> is the auto-generated Object Storage namespace string of
the tenancy in which to create repositories (as shown on the Tenancy Information
page). For example, ansh81vru1zp/[email protected].
Note that for some older tenancies, the namespace string might be the same as the
tenancy name in all lower-case letters (for example, acme-dev).
If your tenancy is federated with Oracle Identity Cloud Service, use the format
<tenancy-namespace>/oracleidentitycloudservice/<username>.
You must have already generated an Oracle Cloud Infrastructure auth token for the user
you specify (see 8. Generate an Auth Token to Enable Login to Oracle Cloud
Infrastructure Registry).
4. When prompted for Password, enter the user's Oracle Cloud Infrastructure auth token.
Having entered the password, Docker might warn you that the password is stored
unencrypted in the Docker configuration file. The warning includes a link to the Docker
documentation where you can find out how to configure a credential helper. Oracle
recommends you review the information in the Docker documentation and consider
using an external credentials store for increased security.
When you have completed the steps in this topic, you have completed the configuration tasks
for your client environment. Go on to Verifying Your Configuration for Function Development
to confirm that the Fn Project CLI can communicate with the API endpoint.
If you have successfully completed the configuration tasks, the Fn Project CLI will be able to
communicate with the API endpoint.
To confirm that the Fn Project CLI can communicate with the API endpoint:
$ fn list apps
3. If you see either of the following, you can proceed to create and deploy functions
because your system is configured correctly:
l A message indicating that no applications have been found, which is expected if
this is the first time the tenancy has been configured for Oracle Functions.
l A list of applications that have already been created, which is expected if other
users are already using the tenancy for functions development.
4. If you see an error message, it's likely that the Fn Project CLI cannot communicate with
the API endpoint due to some incorrect configuration. Do the following:
l Review the configuration tasks to confirm you completed them as instructed (see
Configuring Your Tenancy for Function Development and Configuring Your Client
Environment for Function Development).
l Review the solutions for common problems (see Troubleshooting Oracle
Functions).
To enable you to use the Fn Project CLI with Oracle Functions, you perform a number of
preparatory tasks. See Configuring Your Client Environment for Function Development.
l list all the available applications, use the command fn list apps
l create an application, use a command like fn create app acmeapp --annotation
oracle.com/oci/subnetIds='["ocid1.subnet.oc1.phx.aaaaaaaacnh..."]'
l change the profile that the Fn Project CLI uses for its context, use a command like fn
update context oracle.profile john-oci-profile
To see detailed information about individual Fn Project CLI commands, you can:
From time to time, new versions of the Fn Project CLI are released. To:
l See which version of the Fn Project CLI is currently installed and whether it is the most
recent version, log in to your development environment as a functions developer and
enter fn version in a terminal window. The Fn Project CLI version number is
displayed. If a more recent version of the Fn Project CLI is available, the number of the
latest available version is also displayed.
l Upgrade the Fn Project CLI to the most recent version, reinstall the Fn Project CLI by
following the instructions in 5. Install the Fn Project CLI.
Tip
1. Confirm that you have completed the prerequisite steps for using Oracle Functions, as
described in Preparing for Oracle Functions. Specifically, that you have:
l set up your tenancy (see Configuring Your Tenancy for Function Development)
l set up your development environment (see Configuring Your Client Environment
for Function Development)
2. Log in to the Console as a functions developer.
3. Use the Console to create a new application in Oracle Functions:
a. In the Console, open the navigation menu. Under Solutions and Platform, go to
Developer Services and click Functions.
b. Select the region you intend to use for Oracle Functions. Oracle recommends that
you use the same region as the Docker registry specified in the Fn Project CLI
context (see 6. Create an Fn Project CLI Context to Connect to Oracle Cloud
Infrastructure).
c. Select the compartment specified in the Fn Project CLI context (see 6. Create an
Fn Project CLI Context to Connect to Oracle Cloud Infrastructure).
The Applications page shows the applications already defined in the
compartment.
d. Click Create Application and specify:
The -v option simply shows more detail about what Fn Project commands are doing
(see Using the Fn Project CLI with Oracle Functions).
8. (Optional) Assuming the specified Docker registry is Oracle Cloud Infrastructure
Registry, use the Console to confirm that the helloworld-func image has been pushed to
Oracle Cloud Infrastructure Registry successfully:
a. In the Console, open the navigation menu. Under Solutions and Platform, go to
Developer Services and click Registry.
b. Choose the registry's region.
You see all the repositories in the registry to which you have access. The image
you pushed is in a new repository with a name constructed from:
l the repository name in the address of the Docker registry in the Fn Project
CLI context (see 6. Create an Fn Project CLI Context to Connect to Oracle
Cloud Infrastructure)
l the name of the helloworld-func image
For example, the new repository might be called acme-repo/helloworld-func.
c. Click the name of the new repository. You see details of the helloworld-func
image that's been pushed to Oracle Cloud Infrastructure Registry.
9. (Optional) Use the Console to confirm that the function has been deployed to Oracle
Functions successfully:
a. In the Console, open the navigation menu. Under Solutions and Platform, go to
Developer Services and click Functions.
b. Select the compartment specified in the Fn Project CLI context (see 6. Create an
Fn Project CLI Context to Connect to Oracle Cloud Infrastructure).
The Applications page shows that an application called helloworld-app has been
created.
c. Click the helloworld-app application to see the functions within it.
The Functions page shows that the helloworld-func function has been deployed to
Oracle Functions.
10. In a terminal window, invoke the helloworld-func function by entering:
Congratulations! You've successfully created and deployed your first function to Oracle
Functions!
Creating Applications
You can create applications in Oracle Functions in readiness for deploying functions. An
application need not contain any functions.
You can create applications using the Console, the Fn Project CLI, and the API.
1. Confirm that you have completed the prerequisite steps for using Oracle Functions, as
described in Preparing for Oracle Functions. Specifically, that you have:
l set up your tenancy (see Configuring Your Tenancy for Function Development)
l set up your development environment (see Configuring Your Client Environment
for Function Development)
2. Log in to the Console as a functions developer.
3. In the Console, open the navigation menu. Under Solutions and Platform, go to
Developer Services and click Functions.
4. Select the region you are using with Oracle Functions. Oracle recommends that you use
the same region as the Docker registry that's specified in the Fn Project CLI context
(see 6. Create an Fn Project CLI Context to Connect to Oracle Cloud Infrastructure).
5. Select the compartment specified in the Fn Project CLI context (see 6. Create an Fn
Project CLI Context to Connect to Oracle Cloud Infrastructure).
The Applications page shows the applications already defined in the compartment.
where:
l <app-name> is the name of the new application. Avoid entering confidential
information.
l <subnet-ocid> is the OCID of the subnet (or subnets, up to a maximum of
three) in which to run functions. If a regional subnet has been defined, best
practice is to select that subnet to make failover across availability domains
simpler to implement. If a regional subnet has not been defined and you need to
meet high availability requirements, specify multiple subnets (enclose each OCID
in double quotes separated by commas, in the format '["<subnet-
An application is created in Oracle Functions, in the tenancy and region implied by the
subnet OCID and belonging to the compartment specified in the Fn Project CLI context
file.
3. Verify that the new application has been created by entering:
$ fn list apps
For example:
$ fn list apps
acmeapp
l CreateApplication
l DeleteApplication
l GetApplication
l UpdateApplication
Tip
1. Confirm that you have completed the prerequisite steps for using Oracle Functions, as
described in Preparing for Oracle Functions. Specifically, that you have:
l set up your tenancy (see Configuring Your Tenancy for Function Development)
l set up your development environment (see Configuring Your Client Environment
for Function Development)
2. If the application to which you want to add the function doesn't yet exist in Oracle
Functions, create it now using the Fn Project CLI or the Console. For example, you
might create a new application called acmeapp. See Creating Applications.
3. Log in to your development environment as a functions developer.
4. In a terminal window, change directory to the directory containing the function code.
5. Initialize the function by entering:
$ fn init --runtime <runtime-language> <function-name>
where:
l <runtime-language> is one of the supported runtime languages (currently go,
java, node, python, and ruby are supported)
l <function-name> is the name to use as the function name. If you don't specify a
function name, the name of the current directory (in lower case) is used. Avoid
entering confidential information.
For example:
where <app-name> is the name of the application in Oracle Functions to which you want
to add the function. For example:
$ fn -v deploy --app acmeapp
The -v option simply shows more detail about what Fn Project commands are doing
(see Using the Fn Project CLI with Oracle Functions).
Note that you can build, push, and deploy the function using separate Fn Project
commands, instead of the single fn deploy command.
8. (Optional) Assuming the specified Docker registry is Oracle Cloud Infrastructure
Registry, use the Console to confirm that the image has been pushed to Oracle Cloud
Infrastructure Registry successfully:
a. In the Console, open the navigation menu. Under Solutions and Platform, go to
Developer Services and click Registry.
l Using the Console or the Fn Project CLI command fn create function to create a new
function based on an existing Docker image that has already been pushed to the Docker
registry (as described in this topic).
l Using the single Fn Project CLI command fn deploy to build a new Docker image, push
the image to the Docker registry, and create a new function based on the image in one
step (as described in Creating and Deploying Functions).
l Using the API (see CreateFunction).
When using the Console or the fn create function command to create a new function based
on an existing Docker image, you specify function metadata to store in the Oracle Functions
server. For example, the maximum length of time the function is allowed to execute for.
The existing image on which you base a new function must be suitable for use with Oracle
Functions. Typically, to build and push a suitable image, you or somebody else will use Fn
Project CLI commands and/or Docker CLI commands. For example, having written your
function code and a func.yaml file containing function metadata (perhaps based on the
template helloworld function and func.yaml created using fn init), you can:
With the image in the Docker registry, you can then use the Console to create a function based
on the image, as described in this topic.
The new function is shown in the Console, in the list of functions in the application you
selected.
where:
A new function is created in Oracle Functions, based on the existing image and with the
name you specified
3. Verify that the new function has been created by entering:
$ fn list functions <app-name>
For example:
$ fn list functions acme-app
NAME IMAGE
acme-func phx.ocir.io/ansh81vru1zp/acme-repo/acme-func:0.0.3
l CreateFunction
l DeleteFunction
l GetFunction
l UpdateFunction
Sample Functions
When you set up your development environment for Oracle Functions, simple helloworld
functions are included by default. These sample functions enable you to get up and running
quickly with Oracle Functions.
In addition, a number of how-to's, patterns, use cases, and other samples are available in the
Oracle Functions samples repository on GitHub. These include:
Solution Playbooks
Solution playbooks are targeted, cross-product explanations and architectures showing how to
handle or implement a specific scenario on Oracle Cloud Infrastructure. They are available
from the Oracle Cloud Infrastructure Architecture Center.
The Extend SaaS Applications with a Cloud Native Approach solution playbook shows how to
design a SaaS extension for Oracle Fusion Applications Cloud Service using a Cloud Native
approach.
In this high-level design, Oracle Functions serves as the back-end implementation of a REST
API, secured by Oracle Identity Cloud Service. Authentication is handled by Oracle Cloud
Infrastructure API Gateway.
Reference Architectures
Reference architectures are architectures, configurations, and best practices for deploying on
Oracle Cloud Infrastructure. They are available from the Oracle Cloud Infrastructure
Architecture Center.
The Automate Loading Data to a Data Warehouse Using a Serverless Application reference
architecture shows how to use a serverless function to automate the process of extracting
data from files generated by various databases or applications and loading the data into a
data warehouse for analysis.
In this architecture, the Events service is triggered when zipped CSV files are uploaded to a
specific bucket in Oracle Cloud Infrastructure Object Storage. The emitted event invokes a
function in Oracle Functions, which extracts the data from the uploaded files and loads the
data into an Oracle Autonomous Data Warehouse instance. After the data is loaded to the data
warehouse, the processed CSV files are moved to a different bucket in Object Storage.
You can view applications and functions using the Console, the Fn Project CLI, and the API.
For example:
$ fn list apps
acme-app
l Enter the following command to see more detail about a particular application:
$ fn inspect app <app-name>
For example:
$ fn inspect app acme-app
{
"annotations": {
"oracle.com/oci/appCode": "fht7ns4mn2q",
"oracle.com/oci/compartmentId": "ocid1.compartment.oc1..aaaaaaaaw______nyq",
"oracle.com/oci/subnetIds": [
"ocid1.subnet.oc1.phx.aaaaaaaao..."
],
"oracle.com/oci/tenantId": "ocid1.tenancy.oc1..aaaaaaaap...keq"
},
"created_at": "2018-07-13T17:54:34.000Z",
"id": "ocid1.fnapp.oc1.phx.aaaaaaaaaf______r3ca",
"name": "acme-app",
"updated_at": "2018-07-13T17:54:34.000Z"
}
For example:
$ fn list functions acme-app
NAME IMAGE
acme-func phx.ocir.io/ansh81vru1zp/acme-repo/acme-func:0.0.3
acme-func-dev phx.ocir.io/ansh81vru1zp/acme-repo/acme-func-dev:0.0.7
acme-func-test phx.ocir.io/ansh81vru1zp/acme-repo/acme-func-test:0.0.6
l Enter the following command to see more detail about a particular function:
For example:
$ fn inspect function acme-app acme-func
{
"annotations": {
"fnproject.io/fn/invokeEndpoint": "https://fht7ns4mn2q.us-phoenix-
1.functions.oci.oraclecloud.com/20181201/functions/ocid1.fnfunc.oc1.phx.aaaa____
uxoa/actions/invoke",
"oracle.com/oci/compartmentId": "ocid1.compartment.oc1..aaaaaaaaw______nyq"
},
"app_id": "ocid1.fnapp.oc1.phx.aaaaaaaaaf______r3ca",
"created_at": "2018-07-26T12:50:53.000Z",
"format": "default",
"id": "ocid1.fnfunc.oc1.phx.aaaa____uxoa",
"image": "phx.ocir.io/ansh81vru1zp/acme-repo/acme-func:0.0.3",
"memory": 128,
"name": "acme-func",
"timeout": 30,
"updated_at": "2018-07-26T13:59:18.000Z"
}
Use these API operations to see details about applications and functions:
l ListApplications
l ListFunctions
Invoking Functions
You can invoke a function that you've deployed to Oracle Functions in different ways:
Each of the above invokes the function via requests to the API. Any request to the API must be
authenticated by including a signature and the OCID of the compartment to which the function
belongs in the request header. Such a request is referred to as a 'signed' request. The
signature includes Oracle Cloud Infrastructure credentials in an encrypted form.
If you use the Fn Project CLI or the Oracle Cloud Infrastructure CLI to invoke a function,
authentication is handled for you. See Using the Fn Project CLI to Invoke Functions and Using
the Oracle Cloud Infrastructure CLI to Invoke Functions.
If you use an Oracle Cloud Infrastructure SDK to invoke a function, you can use the SDK to
handle authentication. See Using SDKs to Invoke Functions.
If you make a signed HTTP request to a function's invoke endpoint, you'll have to handle
authentication yourself by including a signature and the OCID of the compartment to which the
function belongs in the request header. You can do this in different ways:
l Using the Oracle Cloud Infrastructure CLI raw-request command. See Sending a
Signed Request to a Function's Invoke Endpoint (using the Oracle Cloud Infrastructure
CLI raw-request command).
l Using a bash script provided by Oracle (commonly referred to as oci-curl). See Sending
a Signed Request to a Function's Invoke Endpoint (using oci-curl).
l Writing code to programmatically sign requests. For information about the required
credentials and how to sign the requests, see Request Signatures.
Tip
where:
l <app-name> is the name of the application containing the function you want to
invoke
l <function-name> is the name of the function you want to invoke
For example:
$ fn invoke helloworld-app helloworld-func
Hello World !
Tip
Hello John !
l you have already installed and configured the Oracle Cloud Infrastructure CLI
l you want to invoke a function as the functions developer that's configured for your
development environment
where:
l <function-ocid> is the OCID of the function you want to invoke. To find out a
function's OCID, use the fn inspect command to see the value of the function's
id property (see Viewing Functions and Applications).
l <output-filepath> is the path and name of a file to write the response to. To
write the response to stdout, specify --file "-"
l <request-parameters> are optionally arguments and values to pass to the
function. If the function is expecting arguments and values as JSON, use a valid
JSON format. For example, --body '{"name":"John"}'. Note that you must
include --body "" in the request, even if there are no request parameters to
pass.
For example:
l $ oci fn function invoke --function-id ocid1.fnfunc.oc1.phx.aaaa____uxoa --file "-" --body
""
Hello World !
Hello John !
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.
where:
l <app-name> is the name of the application containing the function for which you
want to obtain the invoke endpoint
l <function-name> is the name of the function for which you want to obtain the
invoke endpoint
For example:
$ fn inspect function helloworld-app helloworld-func
{
"annotations": {
"fnproject.io/fn/invokeEndpoint": "https://fht7ns4mn2q.us-phoenix-
1.functions.oci.oraclecloud.com/20181201/functions/ocid1.fnfunc.oc1.phx.aaaa____
uxoa/actions/invoke",
...
}
l you have already installed and configured the Oracle Cloud Infrastructure CLI
l you want to invoke a function as the functions developer that's configured for your
development environment
where:
l <invoke-endpoint> is the endpoint you obtained in the earlier step.
l <request-parameters> are optionally arguments and values to pass to the
function. If the function is expecting arguments and values as JSON, use a valid
JSON format. Note that you must include --request-body "" in the request,
even if there are no request parameters to pass.
For example:
l
$ oci raw-request --http-method POST --target-uri https://fht7ns4mn2q.us-phoenix-
1.functions.oci.oraclecloud.com/20181201/functions/ocid1.fnfunc.oc1.phx.aaaa____
uxoa/actions/invoke --request-body ""
Hello World !
l
$ oci raw-request --http-method POST --target-uri https://fht7ns4mn2q.us-phoenix-
1.functions.oci.oraclecloud.com/20181201/functions/ocid1.fnfunc.oc1.phx.aaaa____
uxoa/actions/invoke --request-body '{"name":"John"}'
Hello John !
4. Assuming a passphrase was provided to encrypt the API signing key (as recommended
by Oracle), enter the passphrase when prompted.
l you have already configured oci-curl appropriately (see 7. Set the Context for the Fn
Project CLI Using the oracle.profile Parameter)
l you want to invoke a function as the functions developer that's configured for your
development environment
3. In a terminal window, use the source command to set up the current shell environment
for oci-curl by entering:
$ source <path-to-script>/oci-curl.sh
where <path-to-script> is the path to the location of the oci-curl.sh script (see 3.
Create and Configure a Copy of oci-curl). For example:
$ source ~/oci-curl/oci-curl.sh
4. In the same terminal window in which you entered the source command, use oci-curl to
invoke the function by sending a signed POST request to the function's invoke endpoint
by entering:
oci-curl "<invoke-endpoint-host>" post <filename> "<invoke-endpoint-path>"
where:
l <invoke-endpoint-host> is the first half of the endpoint you obtained in the
earlier step, excluding https:// and up to (and including) .oraclecloud.com.
For example, fht7ns4mn2q.us-phoenix-1.functions.oci.oraclecloud.com
l <filename> is the name of a file containing data to pass to the function (you must
specify a file, even if it's empty) . For example, payload.json
l <invoke-endpoint-path> is the second half of the endpoint you obtained in the
earlier step, from (but not including) .oraclecloud.com onwards. For example,
/20181201/functions/ocid1.fnfunc.oc1.phx.aaaa____uxoa/actions/invoke
5. Assuming a passphrase was provided to encrypt the API signing key (as recommended
by Oracle), enter the passphrase when prompted.
This identity policy enables authenticated users in the specified group to create, update, and
delete functions and applications in the named compartment, and also enables those users to
invoke functions in the compartment. This policy typically meets the requirements of
functions developers developing and testing multiple functions in your organization.
However, this identity policy might be too permissive to meet your security requirements to
control the invocation of functions in production environments. For example, in a production
environment you might want to prevent users from invoking functions completely, or restrict
users to invoking just functions in a specific application, or to invoking just a particular
function.
To control the functions that users in a group can invoke, set up identity policies:
1. To control the functions that a user can invoke, confirm that they are not in a group that
has been given the manage functions-family permission.
2. If you want to enable users in a group to create, update, and delete applications and
functions in a compartment, but to be unable to invoke functions, enter the following
policy statements:
Allow group <group-name> to manage fn-app in compartment <compartment-name>
Allow group <group-name> to manage fn-function in compartment <compartment-name>
3. Specify policy statements to control access to invoke functions, using function and
application OCIDs. For example:
l To enable users to invoke all the functions in a specific application, enter a policy
statement in the following format:
Allow group <group-name> to use fn-invocation in compartment <compartment-name> where
target.app.id = '<application-OCID>'
l To enable users to invoke one specific function, enter a policy statement in the
following format:
Allow group <group-name> to use fn-invocation in compartment <compartment-name> where
target.function.id = '<function-OCID>'
l To enable users to invoke all the functions in all applications except for functions
in one specific application, enter a policy statement in the following format:
l To enable users to invoke all the functions in a compartment except for one
specific function, enter a policy statement in the following format:
Allow group <group-name> to use fn-invocation in compartment <compartment-name> where
target.function.id != '<function-OCID>'
l To enable users to invoke two specific functions, enter a policy statement in the
following format:
Allow group <group-name> to use fn-invocation in compartment <compartment-name> where ANY
{target.function.id='<function-OCID>', target.function.id='<function-OCID>'}
l To enable users to invoke one specific function along with all the functions in a
specific application, a policy statement in the following format:
Allow group <group-name> to use fn-invocation in compartment <compartment-name> where ANY
{target.function.id='<function-OCID>', target.app.id='<application-OCID>'}
l Stores logs in Oracle Cloud Infrastructure. Until an Oracle Cloud Infrastructure logging
service is released, Oracle Functions stores logs as files in a storage bucket in Oracle
Cloud Infrastructure Object Storage.
Note that to view function logs in a storage bucket, the group to which you belong must
have been granted access with the following identity policy statements:
o Allow group <group-name> to manage object-family in compartment
<compartment-name>
o Allow group <group-name> to read objectstorage-namespaces in
compartment <compartment-name> (Usually created when configuring your
tenancy for function development. See Create a Policy to Give Oracle Functions
Users Access to Oracle Cloud Infrastructure Registry Repositories.)
l Stores logs by exporting them to an external logging destination like Papertrail. Note
that to use an external logging destination, you must have set up a VCN with public
subnets and an internet gateway (see Create the VCN and Subnets to Use with Oracle
Functions, if they don't exist already).
l Select the Syslog URL option to store logs in an external logging destination, and
enter the syslog URL to which to export the logs. For example,
tcp://my.papertrail.com:4242
7. Click Save.
Whenever a function is invoked in this application, its logs are stored according to the logging
policy that you specified.
To view the logs for a function that have been stored in a storage bucket in Oracle Cloud
Infrastructure Object Storage:
l A storage bucket is only created after the first log file has been written.
l After a function has been invoked, it takes around 15 minutes for the function's
log files to be written to Object Storage and appear in a storage bucket. So you
won't see a storage bucket for a function until around 15 minutes after the
function has been invoked for the first time.
l If you have waited for longer than 15 minutes and you still don't see a storage
bucket for a function, double-check that the function includes log statements.
7. (Optional) If a large number of log files are shown in the list, enter log/<function-
OCID> in the Search field to reduce the list to a manageable size.
8. Click the name of a log file to download it.
Updating Functions
Having previously created a function definition in the Oracle Functions server, you can change
some, but not all, of the function's properties. For example, you can change the maximum
length of time a function is allowed to execute for, but you cannot change the function's name.
You can change the Docker image on which a function is based. If you do want to change the
image, the replacement image must be suitable for use with Oracle Functions, and must have
already been pushed to the Docker registry. With the replacement image in the Docker
registry, you can then update a function's definition so that it is based on the replacement
image, as described in this topic. If the replacement image has the same name and tag as the
image on which the function was originally based, see Notes About Image Digests.
You can update functions using the Console, the Fn Project CLI, and the API.
where:
l <app-name> is the name of an existing application containing the existing
function.
l <function-name> is the name of the existing function you want to update.
l <image-name> (optionally) is the name of an existing image in the Docker registry
that you now want to base the function on, instead of the previously specified
image. If the image has the same name and tag as the image on which the
function was originally based, see Notes About Image Digests.
l <property> <value> (optionally) is the property you want to update, and the
new value you want it to have. Enter fn update function --help to see a list of
properties and valid values.
For example:
$ fn update function acmeapp acme-func phx.ocir.io/ansh81vru1zp/acme-repo/acme-func:0.0.4 --
timeout 60
The properties of the existing function are updated with the values you specified.
3. Verify that the function has been updated by entering:
$ fn inspect function <app-name> <function-name>
For example:
$ fn inspect function acme-app acme-func
{
"annotations": {
"fnproject.io/fn/invokeEndpoint": "https://fht7ns4mn2q.us-phoenix-
1.functions.oci.oraclecloud.com/20181201/functions/ocid1.fnfunc.oc1.phx.aaaa____
uxoa/actions/invoke",
"oracle.com/oci/compartmentId": "ocid1.compartment.oc1..aaaaaaaaw______nyq"
},
"app_id": "ocid1.fnapp.oc1.phx.aaaaaaaaaf______r3ca",
"created_at": "2018-07-26T12:50:53.000Z",
"format": "default",
"id": "ocid1.fnfunc.oc1.phx.aaaa____uxoa",
"image": "phx.ocir.io/ansh81vru1zp/acme-repo/acme-func:0.0.4",
"memory": 256,
"name": "acme-func",
"timeout": 60,
"updated_at": "2018-07-26T13:59:18.000Z"
}
When you create a function with Oracle Functions, you specify the name and tag of a
particular version of an image on which to base the function. To avoid later inconsistencies,
Oracle Functions also records the unique digest of that particular version of the image.
By default, if you push an updated version of an image to the Docker registry with the same
name and tag as the original version of the image on which a function is based, Oracle
Functions continues to use the original digest to pull the original version of the image. This
might be the behavior you require. However, if you want Oracle Functions to pull the later
version of the image, you can explicitly change the digest that Oracle Functions uses to
identify which version of the image to pull in one of the following ways:
l Use the fn update function command and specify the original name and tag of the
version of the image on which you want the function to be based. For example:
fn update function acmeapp acme-func phx.ocir.io/ansh81vru1zp/acme-
repo/acme-func:0.0.4
Oracle Functions will update the digest recorded for the image on which the function is
based to be the digest of the image in the Docker registry that has the name and tag you
specify.
l Use the fn update function command and specify the digest of the version of the
image on which you want the function to be based. For example:
fn update function acmeapp acme-func –-annotation
oracle.com/oci/imageDigest='"sha256:8af7cb8d7______c498c0"'
Oracle Functions will update the digest recorded for the image on which the function is
based to be the digest you specify.
l Use the Console and click Edit Function on the Function Information tab, re-select
the original name and tag of the version of the image on which the function is currently
based, and click Save Changes. Oracle Functions will update the digest recorded for
the image on which the function is based.
l Use the Oracle Cloud Infrastructure API or an Oracle Cloud Infrastructure SDK (for
more information, see REST APIs and Software Development Kits and Command Line
Interface).
l Deleting a function does not delete the Docker image on which the function is based. To
delete the image, you have to delete it explicitly (see Deleting an Image).
l Deleting applications and functions is permanent. You cannot undelete an application or
function that you've deleted.
l Deleting a function does not necessarily enable you to immediately delete the subnet
and VCN in which the function runs. Expect to wait up to five minutes after the function
was last invoked before you can delete the associated network resources.
You can delete applications and functions using the Console, the Fn Project CLI, and the API.
l when you delete an application, all of its functions are also deleted
l you're always prompted to confirm deletion because you cannot undelete an application
or function later
application as follows:
l If the application does not have functions within it, click Delete to confirm
that you want to delete the application.
l If the application does have functions within it, you are shown a list of the
functions in the application. To delete the application, enter DELETE
<APPLICATION-NAME> in the text box, and click Delete.
Note that deleting an application and all of its functions does not delete the Docker
images on which the functions are based. To delete the images, you have to delete them
explicitly (see Deleting an Image).
6. To delete a function:
a. Click the name of the application containing the function you want to delete.
b. On the Application Detail page, click the name of the function you want to
delete.
c. On the Function Detail page, click Delete and confirm you want to delete the
function.
Note that deleting a function does not delete the Docker image on which the function is
based. To delete the image, you have to delete it explicitly (see Deleting an Image).
To delete applications and functions in Oracle Functions using the Fn Project CLI:
For example:
$ fn delete app acmeapp
3. To delete a function:
a. In a terminal window, enter:
$ fn delete function <app-name> <function-name>
where:
l <app-name> is the name of the application containing the function you want
to delete.
l <function-name> is the name of the function you want to delete.
For example:
$ fn delete function acmeapp acme-func
For example:
$ fn list functions acmeapp
l DeleteApplication
l DeleteFunction
To pass user-defined parameters to a function deployed in Oracle Functions, you create key-
value pairs known as custom configuration parameters. You can create custom configuration
parameters that are:
Oracle Functions combines all the custom configuration parameters (both application-wide
and function-specific) in the application into a single, serially-encoded configuration object
with a maximum allowable size of 4Kb.
cannot save the new custom configuration parameter if the size of the serially-encoded
configuration object would be greater than 4Kb.
8. (Optional) Enter additional custom configuration parameters as required.
where:
l <app-name> is the name of the application containing the functions to which you
want to pass the custom configuration parameter.
l <key> is the name of the custom configuration parameter. The name must only
contain alphanumeric characters and underscores, and must not start with a
number.
l <value> is the value to give to the custom configuration parameter. The value
must only contain printable unicode characters.
For example:
$ fn config app acmeapp username jdoe
where:
l <app-name> is the name of the application containing the function to which you
want to pass the custom configuration parameter.
l <function-name> is the name of the function to which to pass the custom
configuration parameter.
l <key> is the name of the custom configuration parameter. The name must only
contain alphanumeric characters and underscores, and must not start with a
number.
l <value> is the value to give to the custom configuration parameter. The value
must only contain printable unicode characters.
For example:
$ fn config function acmeapp acme-func username jdoe
l CreateFunction
l UpdateFunction
l CreateApplication
l UpdateApplication
For example, you might want a function to download an Excel file and then read its contents.
To meet this requirement, you might create a function that writes the file to the /tmp
directory in the container's filesystem, and then subsequently reads the file.
When writing files to the /tmp directory, the /tmp directory is generally always writable.
However, the maximum allowable size of the /tmp directory depends on the maximum
memory threshold specified for the function:
Note that the /tmp directory might be shared by multiple invocations of the function. A file
written by an earlier invocation of a function could still exist when the function is invoked a
second time. It is your responsibility to delete any files to avoid unexpected behavior.
l You might want a function to get a list of VCNs from the Networking service.
l You might want a function to read data from an Object Storage bucket, perform some
operation on the data, and then write the modified data back to the Object Storage
bucket.
To enable a function to access another Oracle Cloud Infrastructure resource, you have to
include the function in a dynamic group, and then create a policy to grant the dynamic group
access to that resource. For more information about dynamic groups, including the
permissions required to create them, see Managing Dynamic Groups.
Having set up the policy and the dynamic group, you can then include a call to a 'resource
principal provider' in your function code. The resource principal provider uses a resource
provider session token (RPST) that enables the function to authenticate itself with other
Oracle Cloud Infrastructure services. The token is only valid for the resources to which the
dynamic group has been granted access.
Note also that the token is cached for 15 minutes. So if you change the policy or the dynamic
group, you will have to wait for 15 minutes to see the effect of your changes.
Oracle recommends that you use the resource principal provider included in the Oracle Cloud
Infrastructure SDK. However, you might be writing a function in a language that the Oracle
Cloud Infrastructure SDK does not support. Or you might simply not want to use the Oracle
Cloud Infrastructure SDK. In either case, you can write your own custom resource principal
provider to enable a function to authenticate itself with other Oracle Cloud Infrastructure
services, using files and environment variables in the container in which the function is
executing.
l If you want all functions with a specific defined tag to be able to access a
resource, enter a rule similar to the following that adds all functions with
the defined tag to the dynamic group :
ALL {resource.type = 'fnfunc', tag.department.operations.value = '45'}
Note that free-form tags are not supported. For more information about
tagging, see Resource Tags.
d. Click Create Dynamic Group.
Having created a dynamic group that includes the function, you can now create a policy
to give the dynamic group access to the required Oracle Cloud Infrastructure resource.
2. Create a new policy:
to get a list of VCNs from the Networking service. This example uses the Oracle resource
principal provider to extract credentials from the RPST token.
import io
import json
def do(signer):
# List VCNs --------------------------------------------------------
client = oci.core.VirtualNetworkClient({}, signer=signer)
try:
vcns = client.list_vcns(signer.compartment_id)
vcns = [[v.id, v.display_name] for v in vcns.data]
except Exception as e:
vcns = str(e)
return {"vcns": vcns, }
The container in which a function executes includes a directory tree that holds Oracle Cloud
Infrastructure compatible credentials, specifically:
l A resource principal session token (RPST) in a file named rpst. The RPST token is
formatted as a JWT token, and includes claims that identify the function's host tenancy
and compartment.
l A private key for use in making requests to Oracle Cloud Infrastructure services on
behalf of the function, in a file named private.pem.
The following environment variables are set inside the container in which the function
executes:
To enable a function to access another Oracle Cloud Infrastructure service, add code to the
function so that it can authenticate itself with the other resource:
1. Add code that loads the RPST token from the path in the OCI_RESOURCE_PRINCIPAL_
RPST environment variable.
2. Add code that loads the private key from the path in the OCI_RESOURCE_PRINCIPAL_
PRIVATE_PEM environment variable.
3. Add code that uses the RPST token and the private key to create an Oracle Cloud
Infrastructure request signature (see Request Signatures).
4. Add code that constructs the request to the other Oracle Cloud Infrastructure resource.
If necessary, you can identify:
l The endpoints of other Oracle Cloud Infrastructure services in the same
(local) region as the function, using the region identifier in the OCI_RESOURCE_
PRINCIPAL_REGION environment variable.
l The function's host tenancy and compartment, using the res_tenant and res_
compartment claims in the RPST token.
For example, the sample Python function below includes a custom resource principal provider
that extracts credentials from the RPST token. It then submits a GET request to the
IAM API's getTenancy operation to return the OCID of the function's tenancy.
#!/usr/bin/env python3
import base64
import email.utils
import hashlib
import httpsig_cffi.sign
import json
import logging
import os.path
import re
import requests.auth
import urllib.parse
LOG = logging.getLogger(__name__)
class SignedRequestAuth(requests.auth.AuthBase):
"""A requests auth instance that can be reused across requests"""
generic_headers = [
"date",
"(request-target)",
"host"
]
body_headers = [
"content-length",
"content-type",
"x-content-sha256",
]
required_headers = {
"get": generic_headers,
"head": generic_headers,
"delete": generic_headers,
"put": generic_headers + body_headers,
"post": generic_headers + body_headers,
}
raise ValueError(
"Don't know how to sign request verb {}".format(verb))
# Inject body headers for put/post requests, date for all requests
sign_body = verb in ["put", "post"]
self.inject_missing_headers(request, sign_body=sign_body)
if use_host:
host = urllib.parse.urlparse(request.url).netloc
else:
host = None
signed_headers = signer.sign(
request.headers, host=host,
method=request.method, path=request.path_url)
request.headers.update(signed_headers)
return request
def rp_auther():
if os.environ['OCI_RESOURCE_PRINCIPAL_VERSION'] != "2.2":
raise EnvironmentError('{} must be set to the value "2.2"'.format('OCI_RESOURCE_PRINCIPAL_
VERSION'))
rpst = os.environ['OCI_RESOURCE_PRINCIPAL_RPST']
if os.path.isabs(rpst):
with open(rpst) as f:
rpst = f.read()
private_key = os.environ['OCI_RESOURCE_PRINCIPAL_PRIVATE_PEM']
if os.path.isabs(private_key):
with open(private_key) as f:
private_key = f.read()
return get_claims(rpst), SignedRequestAuth('ST${}'.format(rpst), private_key)
def get_claims(rpst):
"""Parse an RPST as a JWT; return a dictionary of claims
The claims that are important are: sub, res_compartment, and res_tenant.
These carry the resource OCID together with its location.
"""
s = rpst.split('.')[1]
s += "=" * ((4 - len(s) % 4) % 4) # Pad to a multiple of 4 characters
return json.loads(base64.b64decode(s).decode('utf-8'))
response = requests.get("https://identity.{}.oraclecloud.com/20160918/tenancies/{}".format(region,
claims['res_tenant']), auth=rp_auth)
print(response.json())
When starting a container to run a function, Oracle Functions always specifies a user named
'fn' with a UID of 1000, and a group name 'fn' with a GID of 1000. No privileges are granted to
UID 1000 and GID 1000, so the container (and the function running inside it) does not acquire
the default capabilities listed in the Docker documentation. In addition, the container is
prevented from gaining privileges.
If you are using your own Dockerfile, include the following lines:
groupadd --gid 1000 fn && \
adduser --uid 1000 --gid fn fn
For example:
FROM oraclelinux:7-slim
WORKDIR /function
ADD . /function/
RUN npm install
Note that if you do not include the groupadd and adduser lines in the above example
Dockerfile, you will see the following error message:
cx_Oracle.DatabaseError: ORA-12560: TNS:protocol adapter error
Depending on the parameter, you can override a default value by specifying an alternative
value in the following ways (note the order of precedence):
The following table indicates the parameters you can set, the default value, and where the
default value can be overridden.
If this limit is
exceeded
during
execution, the
function is
stopped and
an error
message is
logged.
For more information about the above parameters, and other configuration parameters, see
Func files in the Fn Project documentation.
For example, when you use oci-curl to invoke a function, you have to send a request to the
function's invoke endpoint (for example https://fht7ns4mn2q.us-phoenix-
1.functions.oci.oraclecloud.com/20181201/functions/ocid1.fnfunc.oc1.phx.aaaa__
__uxoa/actions/invoke).
You can obtain the appropriate endpoint by making a call to the API, either directly or by using
the Fn Project CLI command:
$ fn inspect function <app-name> <function-name>
Use of Annotations
When you're creating and viewing Oracle Functions resources using the Fn Project CLI,
annotations enable you to identify and specify associated Oracle Cloud Infrastructure
resources.
For example:
l When you're using the Fn Project CLI to create a new application, you use the --
annotation parameter to specify the OCID of the subnet in which to run the function.
l When you're using the Fn Project CLI to view the properties of a function, the
annotations element shows the OCID of the compartment that owns the function.
Note that unlike other configuration parameters and environment variables, annotation values
cannot be passed as arguments to running Docker containers.
Note that DEBUG=1 must appear before the command, and that DEBUG must be in upper case.
Double-check how many applications already exist in your tenancy. Compare that with the
number of applications you're allowed to create. See Oracle Functions Capabilities and Limits.
If you have used the open source Fn Project platform, you might have followed instructions in
the Fn Project documentation to set the FN_REGISTRY environment variable to your Docker
username to enable interaction with the official Docker registry.
The FN_REGISTRY environment variable overrides the value of the registry option in your Fn
Project CLI context.
To use the Fn Project CLI with Oracle Functions, do one of the following:
To upgrade the Fn Project CLI to the most recent version, reinstall the Fn Project CLI by
following the instructions in 5. Install the Fn Project CLI.
If you see the Fn: Missing subnets annotation message, confirm that you entered the
correct application name. For example:
l the application might not be in the compartment currently specified by the Fn Project
CLI context
l the application might have existed previously, but has subsequently been deleted
For example:
l Does user specify the OCID of your Oracle Cloud Infrastructure user account?
l Does fingerprint specify the fingerprint of the public API key value uploaded to the
Console?
l Does key_file specify the full path to the private key file?
See 2. Create a Profile in the Oracle Cloud Infrastructure CLI Configuration File. Also see
API Errors .
Fn: [GET /apps][404] ListApps default &{Fields: Message:Resource is not authorized or not found}
For example:
l Does oracle.compartment-id in your current context correctly specify the OCID of the
compartment that owns deployed functions?
l Have policies been set up correctly to give group access to function-related and network
resources?
l If you are using a local machine as your Oracle Functions development environment,
has your user account been included correctly in the group to which access to function-
related and network resources has been granted?
l If you are using an Oracle Cloud Infrastructure compute instance as your Oracle
Functions development environment, has the compute instance's OCID been included
correctly in the dynamic group that has been granted access to Oracle Cloud
Infrastructure Registry?
l Has a policy been set up to give Oracle Functions access to network resources?
If the syslog URL is invalid or unreachable, you will see the following error when you invoke
the function:
{"code":"FunctionInvokeSyslogUnavailable","message":"Syslog endpoint unavailable"}
Fn: Error invoking function. status: 502 message: Syslog endpoint unavailable
To confirm that the external logging destination's URL is the cause of the error:
2. Deploy the function you want to run. See Creating and Deploying Functions.
3. Invoke the function. See Invoking Functions.
If the function runs successfully, the external logging destination's URL is not reachable from
the subnet in which the function is running. Double-check that:
If Oracle Functions is unable to pull the image, the following message is returned when you
invoke a function:
{"code":"FunctionInvokeImageNotAvailable","message":"Failed to pull function image"}
Fn: Error invoking function. status: 502 message: Failed to pull function image
Possible solutions:
l Double-check that the image specified for the function still exists in the specified
location in Oracle Cloud Infrastructure Registry.
l Double-check that a policy has been created to give Oracle Functions read access to
images stored for functions in repositories in Oracle Cloud Infrastructure Registry. See
Create a Policy to Give the Oracle Functions Service Access to Repositories in Oracle
Cloud Infrastructure Registry.
l Double-check that Oracle Cloud Infrastructure is available (this message is returned if
Oracle Cloud Infrastructure is unexpectedly unavailable).
l Double-check that the VCN includes an internet gateway or service gateway. For Oracle
Functions to be able to access Oracle Cloud Infrastructure Registry to pull an image, the
VCN must include an internet gateway or a service gateway, as follows:
o If public subnets were specified for the application, the VCN must also include an
internet gateway. A route table must include a route rule that targets the internet
gateway, with its Destination CIDR Block property set to 0.0.0.0/0.
o If private subnets were specified for the application, the VCN must also include a
service gateway. The service gateway must be set up to allow access to All
<region> Services In Oracle Services Network. A route table must include
a route rule that targets the service gateway, with its Destination Service
property set to All <region> Services In Oracle Services Network.
If an internet gateway or service gateway has not been defined for the VCN already,
define one now.
If you see this error, double-check that each subnet in the VCN has at least the required
minimum number of free IP addresses specified in Create the VCN and Subnets to Use with
Oracle Functions, if they don't exist already.
l Double-check that a policy has been created to give Oracle Functions access to network
resources. See Create a Policy to Give the Oracle Functions Service Access to Network
Resources.
l Double-check that the subnet specified for the application still exists.
l Double-check that a policy has been created to give Oracle Functions access to network
resources. See Create a Policy to Give the Oracle Functions Service Access to Network
Resources.
l Double-check that the set of DHCP Options in the VCN specified for the application still
exists.
If you see this error, it's likely that a policy has not been created to give Oracle Functions
access to network resources. See Create a Policy to Give the Oracle Functions Service Access
to Network Resources.
Fn: Error invoking function. status: 504 message: Container failed to initialize, please ensure you are
using the latest fdk and check the logs
If you see this error, increase the maximum memory threshold when you invoke the function.
Valid values for the maximum memory threshold are 128MB, 256MB, 512MB, and 1024MB
(see Changing Oracle Functions Default Behavior).
For example, to set a function's maximum memory threshold to 256MB, do one of the
following:
l Click Edit Function on the Function Details page in the Console, and select 256 from
the Memory (in MBs) drop-down list.
l Add the following line to the function's func.yaml file. This will set the maximum
memory threshold to 256MB whenever the function is invoked:
memory: 256
Note that if you edit the func.yaml file, you must re-deploy the function to Oracle
Functions before invoking it again.
It's a good idea to use the latest version of the Fn Project CLI when creating a helloworld
Python function. When you enter the fn init --runtime python <function-name>
command to create the helloworld function, the line memory: 256 is added to the func.yaml
file automatically.
If you see this error, increase the maximum time a function is allowed to run for. For
example, to set the maximum time to 120 seconds, do one of the following:
l Click Edit Function on the Function Details page in the Console, and enter 120 in the
Timeout field.
l Add the following line to the function's func.yaml file. This will set the maximum time
limit to 120 seconds whenever the function is invoked:
timeout: 120
Note that if you edit the func.yaml file, you must re-deploy the function to Oracle
Functions before invoking it again.
The message indicates an unnecessary and unsuccessful attempt to log in to Docker Hub. To
resolve this situation, log out from Docker using the following command:
$ docker logout
Having logged out from Docker, re-run the command to deploy the application.
For more information about this Docker issue, including likely causes and possible
resolutions, see https://github.com/docker/docker-credential-helpers/issues/60.
This message indicates that the function's func.yaml file contains one or more HTTP trigger
definitions. Oracle Functions does not currently support HTTP triggers. To deploy the function,
remove the triggers: section from the func.yaml file.
To avoid creating new func.yaml files containing trigger definitions, follow the instructions in
5. Install the Fn Project CLI to upgrade the Fn Project CLI to the most recent version.
This message indicates that the compute instance does not have access to Oracle Cloud
Infrastructure Registry.
Double-check that a policy statement (similar to the one below) exists in the tenancy's root
compartment to allow a dynamic group that includes the compute instance's OCID to access
Oracle Cloud Infrastructure Registry:
Allow dynamic-group <dynamic-group-name> to read repos in tenancy
For more information about using an Oracle Cloud Infrastructure compute instance as your
development environment, see Different Options for Function Development Environments.
Follow the instructions in 10. Log in to Oracle Cloud Infrastructure Registry to log the Docker
client in to the appropriate Oracle Cloud Infrastructure Registry, an Oracle-managed Docker
registry available in a number of different regions.
This message indicates a problem with the format of the private key. Double-check the
private key is PEM-encoded by opening the private key file in the ~/.oci directory and
confirming that the private key starts with BEGIN RSA PRIVATE KEY. For more information
about generating keys, see 1. Set up an Oracle Cloud Infrastructure API Signing Key for Use
with Oracle Functions.
Function Metrics
You can monitor the health, capacity, and performance of functions you've deployed to Oracle
Functions by using metrics, alarms, and notifications.
This topic describes the metrics emitted by the metric namespace oci_faas (the Oracle
Functions service).
Resources: functions
Prerequisites
IAM policies: To monitor resources, 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. The policy must give you access to the monitoring services as well as the
resources being monitored. 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 more information on
user authorizations for monitoring, see the Authentication and Authorization section for the
related service: Monitoring or Notifications.
For more information about the policy statement required to access metrics emitted by Oracle
Functions, see Create a Policy to Give Oracle Functions Users Access to Function-Related
Resources.
APPLICATIONID
RESOURCEID
RESPONSETYPE
Errors (with
responseType
= "Error")
Throttles
(with
responseType
=
"Throttled")
Missing functions: A function I invoked is The chart range Adjust the chart
missing from the Invocations chart. (time period or x- range or time
axis window) does period as
not cover the time of necessary.
invocation.
Gaps in metrics data: The chart line is No metrics data Smooth out the
discontinuous. I want to see data in the exist in the times display by
charts as a continuous line over time, but indicated by the increasing the
the line has gaps in it. gaps. chart interval to
see if gaps are
removed.
Empty charts: The Errors and Throttles No metrics data Not applicable.
charts never show data. exists for these
charts in the
specified chart
range. No errors
have occurred, and
no requests have
been throttled.
Empty Errors and
Throttles charts are
expected.
Throttles data: The Throttles chart shows Data in the Resubmit the
data. What should I do? Throttles chart throttled
indicates at least one invocation
request to invoke a requests. Submit
function returned a future invocation
'429 Too Many requests less
Requests' error in frequently.
the response.
metrics.
The Applications page shows all the applications in the compartment you selected.
4. Click the name of the application for which you want to view function metrics.
5. Under Resources, click Metrics.
The Metrics page displays a chart for each metric that is emitted by the metric
namespace for Oracle Functions. For more information about the emitted metrics, see
Available Metrics: oci_faas.
For more information about monitoring metrics and using alarms, see Monitoring Overview.
For information about notifications for alarms, see Notifications Overview.
To view default metric charts for all the functions in all the applications in a
compartment
1. Open the navigation menu. Under Solutions and Platform, go to Monitoring and
click Service Metrics.
2. Select the region you are using with Oracle Functions. Oracle recommends that you use
the same region as the Docker registry that's specified in the Fn Project CLI context
(see 6. Create an Fn Project CLI Context to Connect to Oracle Cloud Infrastructure).
3. Select the compartment containing the applications for which you want to view function
metrics.
4. For Metric Namespace, select oci_faas.
The Service Metrics page dynamically updates the page to show charts for each
metric that is emitted by the selected metric namespace. For more information about
the emitted metrics, see Available Metrics: oci_faas.
For more information about monitoring metrics and using alarms, see Monitoring Overview.
For information about notifications for alarms, see Notifications Overview.
MONITORS
Monitors allow you to continuously monitor the health of public-facing endpoints. You can
configure monitors to use either HTTP and ping protocols.
ON-DEMAND PROBES
On-demand probes allow you to execute a one-time probe to assess the health of a public-
facing endpoint. You can configure on-demand probes to use either or both HTTP and ping
protocols. This feature is currently only available via the REST API.
VANTAGE POINTS
Vantage points are geographic locations from which monitors and probes can be executed
to your specified target. Oracle Cloud Infrastructure maintains dozens of vantage points
around the world.
PROTOCOLS
The Health Checks service allows you to configure both HTTP and ping type monitors. Each
type has respective protocols.
To access the Console, you must use a supported browser. You can use the Console link at the
top of this page to go to the sign-in page. Enter your tenancy, user name, and your password.
An administrator in your organization needs to set up groups, compartments, and policies that
control which users can access which services, which resources, and the type of access. For
example, the policies control who can create new users, create and manage the cloud
network, launch instances, create buckets, download objects, etc. For more information, see
Getting Started with Policies. For specific details about writing policies for each of the
different services, see Policy Reference.
If you’re a regular user (not an administrator) who needs to use the Oracle Cloud
Infrastructure resources that your company owns, contact your administrator to set up a user
ID for you. The administrator can confirm which compartment or compartments you should be
using.
See Service Limits for a list of applicable limits and instructions for requesting a limit
increase. To set compartment-specific limits on a resource or resource family, administrators
can use compartment quotas.
If you're new to policies, see Getting Started with Policies and Common Policies. For more
details about policies for Health Checks, see Details for the Health Checks Service.
Policy examples:
Tagging Resources
You can apply tags to your resources to help you organize them according to your business
needs. You can apply tags at the time you create a resource, or you can update the resource
later with the desired tags. For general information about applying tags, see Resource Tags.
Note
An administrator in your organization needs to set up groups, compartments, and policies that
control which users can access which services, which resources, and the type of access. For
example, the policies control who can create new users, create and manage the cloud
network, launch instances, create buckets, download objects, etc. For more information, see
Getting Started with Policies. For specific details about writing policies for each of the
different services, see Policy Reference.
If you’re a regular user (not an administrator) who needs to use the Oracle Cloud
Infrastructure resources that your company owns, contact your administrator to set up a user
ID for you. The administrator can confirm which compartment or compartments you should be
using.
Endpoints
The Health Checks API can be accessed via the following endpoints:
l https://healthchecks.ap-chuncheon-1.oraclecloud.com/20180501
l https://healthchecks.ap-hyderabad-1.oraclecloud.com/20180501
l https://healthchecks.ap-melbourne-1.oraclecloud.com/20180501
l https://healthchecks.ap-mumbai-1.oraclecloud.com/20180501
l https://healthchecks.ap-osaka-1.oraclecloud.com/20180501
l https://healthchecks.ap-seoul-1.oraclecloud.com/20180501
l https://healthchecks.ap-sydney-1.oraclecloud.com/20180501
l https://healthchecks.ap-tokyo-1.oraclecloud.com/20180501
l https://healthchecks.ca-montreal-1.oraclecloud.com/20180501
l https://healthchecks.ca-toronto-1.oraclecloud.com/20180501
l https://healthchecks.eu-amsterdam-1.oraclecloud.com/20180501
l https://healthchecks.eu-frankfurt-1.oraclecloud.com/20180501
l https://healthchecks.eu-zurich-1.oraclecloud.com/20180501
l https://healthchecks.me-jeddah-1.oraclecloud.com/20180501
l https://healthchecks.sa-saopaulo-1.oraclecloud.com/20180501
l https://healthchecks.uk-london-1.oraclecloud.com/20180501
l https://healthchecks.us-ashburn-1.oraclecloud.com/20180501
l https://healthchecks.us-phoenix-1.oraclecloud.com/20180501
HTTP - Configure a GET or HEAD request using HTTP/1.1 to test the target for availability. The
probe results are returned in JSON and include the HTTP Status Code and DNS lookup,
connection and response timings.
HTTPS - Configure an encrypted HTTPS GET or HEAD request to test the availability of any
secure hosted target. Defaults to port 443. The probe results are returned in JSON and include
the HTTP Status Code and DNS lookup, connection and response timings.
ICMP - Configure an ICMP echo request ping. The results include the round trip time (RTT)
latency.
TCP - Configure a TCP handshake to the specified end point. You should be sure to own this
endpoint as testing this connection can be costly to the recipient. The results include the round
trip time (RTT) latency.
Create A Monitor
Monitors allow you to monitor the health of endpoints over time. The following example shows
how to create an HTTPS monitor that checks the health of www.example.com at an interval of
every 30 seconds using a GET request.
POST /20180501/httpMonitors
{
"compartmentId":"ocid1.compartment.oc1..<unique_ID>",
"protocol":"HTTPS",
"port":443,
"targets":[
"www.example.com"
],
"timeoutInSeconds":30,
"method":"GET",
"displayName":"Example HTTP monitor",
"intervalInSeconds":30
}
Targets can be either hostnames or IP addresses and the path field can be used to specify an
optional path, such as www.example.com/project/help.htm. Optionally, you can specify which
geographic locations you would like the monitor to launch from by using the
vantagePointNames field. At least one vantage point must be listed when using this field. For
a list of available vantage points, see Vantage Points.
A 200 response will be returned with the successful creation of a probe and the results of the
probe can be retrieved from the URL in the resultsUrl field of the response.
{
"id":"ocid1.httpmonitor.OC2...<unique_ID>",
"compartmentId":"ocid1.compartment.oc1..<unique_ID>",
"resultsUrl":"https://healthchecks.us-ashburn-
1.oraclecloud.com/20180501/httpProbeResults/ocid1.httpmonitor.OC2...<unique_ID>",
"targets":[
"www.example.com",
"www.oracle.com"
],
"vantagePointNames":[
"ibm-sjc",
"aws-dub",
"dgo-nyc"
],
"protocol":"HTTPS",
"timeoutInSeconds":30,
"displayName":"Example Monitor",
"intervalInSeconds":30,
"isEnabled":true
}
Note
{
"compartmentId": "ocid1.compartment.oc1..<unique_ID>",
"protocol": "HTTP",
"targets": [
"www.example.com"
],
"timeoutInSeconds": 30,
"method": "GET"
}
Targets can be either hostnames or IP addresses and the path field can be used to specify an
optional path, such as www.example.com/project/help.htm. Additionally, you can specify
which geographic locations you would like the probe to launch from by using the
vantagePointNames field. For a list of available vantage points, see Vantage Points.
A 200 response will be returned with the successful creation of a probe and the results of the
probe can be retrieved from the URL in the resultsUrl field of the response. It will take a
few moments for results to display once the tests have been configured.
{
"id":"ocid1.pingprobe.OC2..<unique_ID>",
"compartmentId":"ocid1.compartment.oc1..<unique_ID>",
"resultsUrl":"https://healthchecks.us-ashburn-
1.oraclecloud.com/20180501/pingProbeResults/ocid1.pingprobe.OC2..<unique_ID>",
"targets":[
"www.example.com"
],
"vantagePointNames":[
"ibm-sjc",
"aws-dub",
"dgo-nyc"
],
"protocol":"ICMP",
"timeoutInSeconds":30
}
Note
Retrieving results for an on-demand probe or monitor requires the probe or monitor's
configuration ID as a parameter. On-demand probe and configuration IDs are assigned upon
their creation and are returned in the id field of the POST response. You can also use the
ListHttpMonitor method to retrieve a list of currently configured monitors and probes using
HTTP protocols. Use the ListPingMonitors method to retrieve a list of currently configured
monitors and probes using TCP and ICMP protocols.
"connection": {
"connectDuration": 114,
"secureConnectDuration": 99,
"address": "93.184.216.34",
"port": 443
},
"dns":{
"domainLookupDuration": 29,
"addresses": [
"93.184.216.34",
"2606:2800:220:1:248:1893:25c8:1946"
]
},
"statusCode": 200,
"fetchStart": 1517323711505,
"domainLookupStart": 1517323711505,
"domainLookupEnd": 1517323711534,
"connectStart": 1517323711535,
"secureConnectionStart": 1517323711550,
"connectEnd": 1517323711649,
"requestStart": 1517323711649,
"responseStart": 1517323711673,
"responseEnd": 1517323711676,
"duration": 171,
"encodedBodySize": 1270,
"isTimedOut": false,
"isHealthy": true
}
Vantage Points
Vantage points are geographic locations from which monitors and probes can be launched.
Oracle Cloud Infrastructure maintains vantage points on the infrastructure of cloud providers
around the world, including AWS, IBM, and Azure. The list below is a sampling of the vantage
points available. The list of vantage points is dynamic and changes frequently. Use the
ListHealthChecksVantagePoints method to return a list of available vantage points.
Important
1. Open the navigation menu. Under Solutions and Platform, go to Monitoring and
click Health Checks.
2. Click Create Health Check.
3. In the Create Health Check dialog box, enter the following:
l Health Check Name: The name used for the health check. Avoid entering
confidential information.
l Compartment: Select the compartment the health check runs in.
l Target(s): The IP address or fully qualified domain name (FQDN) of the host
being monitored. Additional targets can be added.
l Vantage Points: Select the location from which the health of the target is
monitored. No more than ten vantage points can be added.
l Request Type: Select the type of request sent to monitor the target.
o HTTP - Enter the following:
n Protocol: The network protocol used to interact with your endpoint,
such as HTTP protocol, which initializes an HTTP handshake with your
endpoint.
n Port: The port for the monitor to look for a connection. The default is
port 80 for HTTP. For HTTPS, use port 443.
n Path: The specific path on the target to be monitored.
n Header Name: (Optional) The name displayed in the request header
as part of the health check. Avoid entering confidential information.
n Header Value: (Optional) Specifies the data requested by the
header. Click + Add Header to add multiple headers in succession.
n Method: Select the HTTP method used for the health check.
n Timeout: Select the maximum time to wait for a reply before
marking the health check as failed.
n Interval: Select the period of time between health checks of the
target.
o Ping - Enter the following:
n Protocol: The network protocol used to interact with your endpoint,
such as HTTP protocol, which initializes an HTTP handshake with your
endpoint.
n Port: If you have selected the TCP protocol, enter the port for the
monitor to look for a connection. The default port is 80.
n Timeout: Select the maximum time to wait for a reply before
marking the health check as failed.
n Interval: Select the period of time between health checks of the
target.
l Tags: Optionally, you can apply 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.
4. Click Create Health Check.
The health check is added to the health check list. To view more details, click the health check
name. It will take a few moments for results to display once the tests have been configured.
2. Select the check box for the health check you want to edit.
Tip
Tip
The status of the health check changes to Disabled in the health check list.
Tip
Tip
3. Click the drop-down arrow beside the Timestamp to view the monitor result details.
You can use the API to download the data.
Tip
l Use the CreateHTTPMonitor operation to create a Health Check monitor that uses the
HTTP protocol.
l Use the CreatePingMonitor operation to create a Health Check monitor that uses the
ping protocol.
l Use the ListHealthChecksVantagePoints to retrieve a list of available vantage points
from which to execute monitors.
l Use the UpdateHttpMonitor operation to update the configuration of an HTTP health
check monitor. You can also use this operation to disable an HTTP monitor by setting the
isEnabled field to false.
l Use the UpdatePingMonitor operation to update the configuration of ping health check
monitor. You can also use this operation to disable a ping monitor by setting the
isEnabled field to false.
l Use the DeleteHttpMonitor operation to remove an HTTP health check monitor from
your setup.
l Use the DeletePingMonitor operation to remove a ping health check monitor from your
setup.
l Use the ListHttpProbeResults operation to retrieve the results of an HTTP health check
monitor.
l Use the ListPingProbeResults operation to retrieve results of a ping health check
monitor.
This topic describes the metrics emitted by the metric namespace oci_healthchecks (the
Health Checks service).
Prerequisites
l IAM policies: To monitor resources, 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. The policy must give you access to the monitoring
services as well as the resources being monitored. 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 more information on user authorizations for monitoring, see the
Authentication and Authorization section for the related service: Monitoring or
Notifications.
RESOURCEID
resourceDisplayNa
me
statusCode2xx
statusCode3xx
statusCode4xx
statusCode5xx
protocol
errorMessage
protocol
errorMessage
icmpCode
For more information about monitoring metrics and using alarms, see Monitoring Overview.
For information about notifications for alarms, see Notifications Overview.
Note
Components of IAM
IAM uses the components described in this section. To better understand how the components
fit together, see Example Scenario.
RESOURCE
The cloud objects that your company's employees create and use when interacting with
Oracle Cloud Infrastructure. For example: compute instances, block storage volumes,
virtual cloud networks (VCNs), subnets, route tables, etc.
USER
An individual employee or system that needs to manage or use your company's Oracle
Cloud Infrastructure resources. Users might need to launch instances, manage remote
disks, work with your virtual cloud network, etc. End users of your application are not
typically IAM users. Users have one or more IAM credentials (see User Credentials).
GROUP
A collection of users who all need the same type of access to a particular set of resources
or compartment.
DYNAMIC GROUP
A special type of group that contains resources (such as compute instances) that match
rules that you define (thus the membership can change dynamically as matching
resources are created or deleted). These instances act as "principal" actors and can make
API calls to services according to policies that you write for the dynamic group.
NETWORK SOURCE
A group of IP addresses that are allowed to access resources in your tenancy. The IP
addresses can be public IP addresses or IP addresses from a VCN within your tenancy.
After you create the network source, you use policy to restrict access to only requests that
originate from the IPs in the network source.
COMPARTMENT
TENANCY
The root compartment that contains all of your organization's Oracle Cloud Infrastructure
resources. Oracle automatically creates your company's tenancy for you. Directly within
the tenancy are your IAM entities (users, groups, compartments, and some policies; you
can also put policies into compartments inside the tenancy). You place the other types of
cloud resources (e.g., instances, virtual networks, block storage volumes, etc.) inside the
compartments that you create.
POLICY
A document that specifies who can access which resources, and how. Access is granted at
the group and compartment level, which means you can write a policy that gives a group a
specific type of access within a specific compartment, or to the tenancy itself. If you give
a group access to the tenancy, the group automatically gets the same type of access to all
the compartments inside the tenancy. For more information, see Example Scenario and
How Policies Work. The word "policy" is used by people in different ways: to mean an
individual statement written in the policy language; to mean a collection of statements in
a single, named "policy" document (which has an Oracle Cloud ID (OCID) assigned to it);
and to mean the overall body of policies your organization uses to control access to
resources.
HOME REGION
The region where your IAM resources reside. All IAM resources are global and available
across all regions, but the master set of definitions reside in a single region, the home
region. You must make changes to your IAM resources in your home region. The changes
will be automatically propagated to all regions. For more information, see Managing
Regions.
FEDERATION
Your tenancy also automatically has a policy that gives the Administrators group access to all
of the Oracle Cloud Infrastructure API operations and all of the cloud resources in your
tenancy. You can neither change nor delete this policy. Any other users you put into the
Administrators group will have full access to all of the services. This means they can create
and manage IAM resources such as, groups, policies, and compartments. And they can create
and manage the cloud resources such as virtual cloud networks (VCNs), instances, block
storage volumes, and any other new types of Oracle Cloud Infrastructure resources that
become available in the future.
Example Scenario
The goal of this scenario is to show how the different IAM components work together, and
basic features of policies.
In this scenario, Acme Company has two teams that will be using Oracle Cloud Infrastructure
resources for infrastructure: Project A and Project B. In reality, your company may have
many more.
Acme Company plans to use a single virtual cloud network (VCN) for both teams, and wants a
network administrator to manage the VCN.
Acme Company also wants the Project A team and Project B team to each have their own set
of instances and block storage volumes. The Project A team and Project B teams shouldn't be
able to use each other's instances. These two teams also shouldn't be allowed to change
anything about the VCN set up by the network administrator. Acme Company wants each team
to have administrators for that team's resources. The administrators for the Project A team
can decide who can use the Project A cloud resources, and how. Same for the Project B team.
Acme Company signs up to use Oracle Cloud Infrastructure and tells Oracle that an employee
named Wenpei will be the default administrator. In response, Oracle:
Wenpei next creates several groups and users (see the following diagram). She:
l Creates groups called NetworkAdmins, A-Admins, and B-Admins (these last two are for
Project A and Project B within the company)
l Creates a user called Alex and puts him in the Administrators group.
l Leaves the new groups empty.
To learn how to create groups, see Working with Groups. To learn how to create users and
put them in groups, see Working with Users.
Wenpei next creates compartments to group resources together (see the following diagram).
She:
l Creates a compartment called Networks to control access to the Acme Company's VCN,
subnets, IPSec VPN, and other components from Networking.
Wenpei then creates a policy to give the administrators for each compartment their required
level of access. She attaches the policy to the tenancy, which means that only users with
access to manage policies in the tenancy can later update or delete the policy. In this
scenario, that is only the Administrators group. The policy includes multiple statements that:
l Give the NetworkAdmins group access to manage networks and instances (for the
purposes of easily testing the network) in the Networks compartment
l Give both the A-Admins and B-Admins groups access to use the networks in the
Networks compartment (so they can create instances into the network).
l Give the A-Admins group access to manage all resources in the Project-A compartment.
l Give the B-Admins group access to manage all resources in the Project-B compartment.
Here's what that policy looks like (notice it has multiple statements in it):
Allow group NetworkAdmins to manage virtual-network-family in compartment Networks
Allow group NetworkAdmins to manage instance-family in compartment Networks
Notice the difference in the verbs (manage, use), as well as the resources (virtual-
network-family, instance-family, all-resources). For more information about them,
see Verbs and Resource-Types.To learn how to create policies, see To create a policy.
Important
Acme Company wants to let the administrators of the Project-A and Project-B compartments
decide which users can use the resources in those compartments. So Wenpei creates two
more groups: A-Users and B-Users. She then adds six more statements that give the
compartment admins the required access they need in order to add and remove users from
those groups:
Allow group A-Admins to use users in tenancy where target.group.name='A-Users'
Allow group A-Admins to use groups in tenancy where target.group.name='A-Users'
Notice that this policy doesn't let the project admins create new users or manage credentials
for the users. It lets them decide which existing users can be in the A-Users and B-Users
groups. The last two statements are necessary for A-Admins and B-Admins to list all the users
and groups, and confirm which users are in which groups.
At this point, Alex is in the Administrators group and now has access to create new users. So
he provisions users named Leslie, Jorge, and Cheri and places them in the NetworkAdmins, A-
Admins, and B-Admins groups, respectively. Alex also creates other users who will eventually
be put in the A-Users and B-Users groups by the admins for Project A and Project B.
Leslie (in the NetworkAdmins group) has access to manage virtual-network-family and
instance-family in the Networks compartment. She creates a virtual cloud network (VCN)
with a single subnet in that compartment. She also sets up an Internet gateway for the VCN,
and updates the VCN's route table to allow traffic via that gateway. To test the VCN's
connectivity to the on-premises network, she launches an instance in the subnet in the VCN.
As part of the launch request, she must specify which compartment the instance should reside
in. She specifies the Networks compartment, which is the only one she has access to. She
then confirms connectivity from the on-premises network to the VCN by logging in to the
instance via SSH from the on-premises network.
Leslie terminates her test instance and lets Jorge and Cheri know that the VCN is up and
running and ready to try out. She lets them know that their compartments are named Project-
A and Project-B respectively. For more information about setting up a cloud network, see
Overview of Networking. For information about launching instances into the network, see
Overview of the Compute Service.
Jorge and Cheri now need to set up their respective compartments. Each admin needs to do
the following:
Jorge and Cheri both launch instances into the subnet in the VCN, into their respective team's
compartments. They create and attach block volumes to the instances. Only the compartment
admins can launch/terminate instances or attach/detach block volumes in their respective
team's compartments.
Important
Next, Jorge puts several of the users that Alex created into the A-Users group. Cheri does the
same for B-Users.
Then Jorge writes a policy that gives users the level of access they need in the Project-A
compartment.
Allow group A-Users to use instance-family in compartment Project-A
Allow group A-Users to use volume-family in compartment Project-A
Allow group A-Users to inspect virtual-network-family in compartment Networks
This lets them use existing instances (with attached block volumes) that the compartment
admins already launched in the compartment, and stop/start/reboot them. It does not let A-
Users create/delete or attach/detach any volumes. To give that ability, the policy would need
to include manage volume-family.
Jorge attaches this policy to the Project-A compartment. Anyone with the ability to manage
policies in the compartment can now modify or delete this policy. Right now, that is only the
A-Admins group (and the Administrators group, which can do anything throughout the
tenancy).
Cheri creates and attaches her own policy to the Project-B compartment, similar to Jorge's
policy:
Allow group B-Users to use instance-family in compartment Project-B
Allow group B-Users to use volume-family in compartment Project-B
Allow group B-Users to inspect virtual-network-family in compartment Networks
Now the A-Users and B-Users can work with the existing instances and attached volumes in
the Project-A and Project-B compartments, respectively. Here's what the layout looks like:
For more information about basic and advanced features of policies, see How Policies Work.
For examples of other typical policies your organization might use, see Common Policies.
This experience is different when you're viewing the lists of users, groups, dynamic groups,
and federation providers. Those reside in the tenancy itself (the root compartment), not in an
individual compartment.
As for policies, they can reside in either the tenancy or a compartment, depending on where
the policy is attached. Where it's attached controls who has access to modify or delete it. For
more information, see Policy Attachment.
l Authentication policies
l Credentials
l Dynamic groups
l Groups
l Identity Providers
l Multi-factor Authentication TOTP Devices
l Policies
l Users
Resource Identifiers
Most types of Oracle Cloud Infrastructure resources have a unique, Oracle-assigned identifier
called an Oracle Cloud ID (OCID). For information about the OCID format and other ways to
identify your resources, see Resource Identifiers.
For general information about using the API, see REST APIs.
Note
l Make sure you're familiar with the basic IAM components, and read through the
example scenario: Overview of Oracle Cloud Infrastructure Identity and Access
Management
l Think about how to organize your resources into compartments: See "Setting Up Your
Tenancy" in the Oracle Cloud Infrastructure Getting Started Guide
l Learn the basics of how policies work: How Policies Work
l Check out some typical policies: Common Policies
l Read the FAQs below
Policy FAQs
Which of the services within Oracle Cloud Infrastructure can I control access to
through policies?
All of them, including IAM itself. You can find specific details for writing policies for each
service in the Policy Reference.
Why should I separate resources by compartment? Couldn't I just put all the
resources into one compartment and then use policies to control who has
access to what?
You could put all your resources into a single compartment and use policies to control access,
but then you would lose the benefits of measuring usage and billing by compartment, simple
policy administration at the compartment level, and clear separation of resources between
projects or business units.
l Enterprise companies typically have multiple users that need similar permissions, so
policies are designed to give access to groups of users, not individual users. A user
gains access by being in a group.
l Policies are designed to allow access; there's no explicit "deny" when you write a policy.
If you need to grant access to a particular user, you can add a condition to the policy that
specifies the user's OCID in a variable. This construction restricts the access granted in the
policy to only the user specified in the condition. For example:
allow any-user to read object-family in compartment ObjectStorage where request.user.id
='ocid1.user.oc1..<user_OCID>'
For information about using conditions and variables in policies, see Conditions.
Overview of Policies
A policy is a document that specifies who can access which Oracle Cloud Infrastructure
resources that your company has, and how. A policy simply allows a group to work in certain
ways with specific types of resources in a particular compartment. If you're not familiar with
users, groups, or compartments, see Overview of Oracle Cloud Infrastructure Identity and
Access Management.
In general, here’s the process an IAM administrator in your organization needs to follow:
1. Define users, groups, and one or more compartments to hold the cloud resources for
your organization.
2. Create one or more policies, each written in the policy language. See Common Policies.
3. Place users into the appropriate groups depending on the compartments and resources
they need to work with.
4. Provide the users with the one-time passwords that they need in order to access the
Console and work with the compartments. For more information, see User Credentials.
After the administrator completes these steps, the users can access the Console, change their
one-time passwords, and work with specific cloud resources as stated in the policies.
Policy Basics
To govern control of your resources, your company will have at least one policy. Each policy
consists of one or more policy statements that follow this basic syntax:
Allow group <group_name> to <verb> <resource-type> in compartment <compartment_name>
Notice that the statements always begin with the word Allow. Policies only allow access; they
cannot deny it. Instead there's an implicit deny, which means by default, users can do nothing
and have to be granted access through policies. (There's one exception to this rule; see Can
users do anything without an administrator writing a policy for them?)
An administrator in your organization defines the groups and compartments in your tenancy.
Oracle defines the possible verbs and resource-types you can use in policies (see Verbs and
Resource-Types).
In some cases you'll want the policy to apply to the tenancy and not a compartment inside the
tenancy. In that case, change the end of the policy statement like so:
Allow group <group_name> to <verb> <resource-type> in tenancy
For information about how many policies you can have, see Service Limits.
A Few Examples
Let's say your administrator creates a group called HelpDesk whose job is to manage users
and their credentials. Here is a policy that enables that:
Allow group HelpDesk to manage users in tenancy
Notice that because users reside in the tenancy (the root compartment), the policy simply
states the word tenancy, without the word compartment in front of it.
Next, let's say you have a compartment called Project-A, and a group called A-Admins whose
job is to manage all of the Oracle Cloud Infrastructure resources in the compartment. Here's
an example policy that enables that:
Allow group A-Admins to manage all-resources in compartment Project-A
Be aware that the policy directly above includes the ability to write policies for that
compartment, which means A-Admins can control access to the compartment's resources. For
more information, see Policy Attachment.
If you wanted to limit A-Admins' access to only launching and managing compute instances
and block storage volumes (both the volumes and their backups) in the Project-A
compartment, but the network itself lives in the Networks compartment, then the policy could
instead be:
Allow group A-Admins to manage instance-family in compartment Project-A
The third statement with the virtual-network-family resource-type enables the instance
launch process, because the cloud network is involved. Specifically, the launch process
creates a new VNIC and attaches it to the subnet where the instance resides.
Typically you'll specify a group or compartment by name in the policy. However, you can use
the OCID instead. Just make sure to add "id" before the OCID. For example:
Allow group
id ocid1.group.oc1..aaaaaaaaqjihfhvxmumrl3isyrjw3n6c4rzwskaawuc7i5xwe6s7qmnsbc6a
Verbs
Oracle defines the possible verbs you can use in your policies. Here's a summary of the verbs,
from least amount of access to the most:
use Includes read plus the ability to work with existing resources Day-to-day
(the actions vary by resource type). Includes the ability to end users of
update the resource, except for resource-types where the resources
"update" operation has the same effective impact as the
"create" operation (e.g., UpdatePolicy,
UpdateSecurityList, etc.), in which case the "update"
ability is available only with the manage verb. In general, this
verb does not include the ability to create or delete that type
of resource.
The verb gives a certain general type of access (e.g., inspect lets you list and get
resources). When you then join that type of access with a particular resource-type in a policy
(e.g., Allow group XYZ to inspect compartments in the tenancy), then you give that
group access to a specific set of permissions and API operations (e.g., ListCompartments,
GetCompartment). For more examples, see Details for Verbs + Resource-Type Combinations.
The Policy Reference includes a similar table for each service, giving you a list of exactly
which API operations are covered for each combination of verb and resource-type.
Users: Access to both manage users and manage groups lets you do anything with users and
groups, including creating and deleting users and groups, and adding/removing users from
groups. To add/remove users from groups without access to creating and deleting users and
groups, only both use users and use groups are required. See Common Policies.
Policies: The ability to update a policy is available only with manage policies, not use
policies, because updating a policy is similar in effect to creating a new policy (you can
overwrite the existing policy statements). In addition, inspect policies lets you get the full
contents of the policies.
Object Storage objects: inspect objects lets you list all the objects in a bucket and do a
HEAD operation for a particular object. In comparison, read objects lets you download the
object itself.
Load Balancing resources: Be aware that inspect load-balancers lets you get all
information about your load balancers and related components (backend sets, etc.).
Networking resources:
Be aware that the inspect verb not only returns general information about the cloud
network's components (for example, the name and OCID of a security list, or of a route
table). It also includes the contents of the component (for example, the actual rules in the
security list, the routes in the route table, and so on).
Also, the following types of abilities are available only with the manage verb, not the use verb:
Important
Resource-Types
Oracle also defines the resource-types you can use in your policies. First, there are individual
types. Each individual type represents a specific type of resource. For example, the vcns
resource-type is specifically for virtual cloud networks (VCNs).
To make policy writing easier, there are family types that include multiple individual
resource-types that are often managed together. For example, the virtual-network-family
type brings together a variety of types related to the management of VCNs (e.g., vcns,
subnets, route-tables, security-lists, etc.). If you need to write a more granular policy
that gives access to only an individual resource-type, you can. But you can also easily write a
policy to give access to a broader range of resources.
Important
Note that there are other ways to make policies more granular, such as the ability to specify
conditions under which the access is granted. For more information, see Advanced Policy
Features.
the volume-backups resource-type. The sum of the individual statements, regardless of their
location in the overall set of policies, gives George access to CreateVolumeBackup.
Policy Inheritance
A basic feature of policies is the concept of inheritance: Compartments inherit any policies
from their parent compartment. The simplest example is the Administrators group, which
automatically comes with your tenancy (see The Administrators Group and Policy). There's a
built-in policy that enables the Administrators group to do anything in the tenancy:
Allow group Administrators to manage all-resources in tenancy
Because of policy inheritance, the Administrators group can also do anything in any of the
compartments in the tenancy.
Policy Attachment
Another basic feature of policies is the concept of attachment. When you create a policy you
must attach it to a compartment (or the tenancy, which is the root compartment). Where
you attach it controls who can then modify it or delete it. If you attach it to the
tenancy (in other words, if the policy is in the root compartment), then anyone with access to
manage policies in the tenancy can then change or delete it. Typically that's the
Administrators group or any similar group you create and give broad access to. Anyone with
access only to a child compartment cannot modify or delete that policy.
If you instead attach the policy to a child compartment, then anyone with access to manage
the policies in that compartment can change or delete it. In practical terms, this means it's
easy to give compartment administrators (i.e., a group with access to manage all-
resources in the compartment) access to manage their own compartment's policies, without
giving them broader access to manage policies that reside in the tenancy. For an example that
uses this kind of compartment administrator design, see Example Scenario. (Recall that
because of policy inheritance, users with access to manage policies in the tenancy
automatically have the ability to manage policies in compartments inside the tenancy.)
The process of attaching the policy is easy (whether attaching to a compartment or the
tenancy): If you're using the Console, when you add the policy to IAM, simply make sure
you're in the desired compartment when you create the policy. If you're using the API, you
specify the OCID of the desired compartment (either the tenancy or other compartment) as
part of the request to create the policy.
When you attach a policy to a compartment, you must be in that compartment and you must
indicate directly in the statement which compartment it applies to. If you are not in the
compartment, you'll get an error if you try to attach the policy to a different compartment.
Notice that attachment occurs during policy creation, which means a policy can be attached to
only one compartment. To learn how to attach a policy to a compartment, see To create a
policy.
As described in the previous section, a policy statement must specify the compartment for
which access is being granted (or the tenancy). Where you create the policy determines who
can update the policy. If you attach the policy to the compartment or its parent, you can
simply specify the compartment name. If you attach the policy further up the hierarchy, you
must specify the path. The format of the path is each compartment name (or OCID) in the
path, separated by a colon:
<compartment_level_1>:<compartment_level_2>: . . . <compartment_level_n>
For example, assume you have a three-level compartment hierarchy, shown here:
You want to create a policy to allow NetworkAdmins to manage VCNs in CompartmentC. If you
want to attach this policy to CompartmentC or to its parent, CompartmentB, write this policy
statement:
Allow group NewtworkAdmins to manage virtual-network-family in compartment CompartmentC
However, if you want to attach this policy to CompartmentA (so that only administrators of
CompartmentA can modify it), write this policy statement that specifies the path:
Allow group NewtworkAdmins to manage virtual-network-family in compartment CompartmentB:CompartmentC
To attach this policy to the tenancy, write this policy statement that specifies the path from
CompartmentA to CompartmentC:
Allow group NewtworkAdmins to manage virtual-network-family in compartment
CompartmentA:CompartmentB:CompartmentC
It's possible that the definition of a verb or resource-type could change in the future. For
example, let's say that the virtual-network-family resource-type changes to include a new
kind of resource that's been added to Networking. By default, your policies automatically stay
current with any changes in service definition, so any policy you have that gives access to
virtual-network-family would automatically include access to the newly added resource. If
you'd prefer a different behavior, see Policy Language Version.
The Policy Reference includes details of the specific resource-types for each service, and
which verb + resource-type combination gives access to which API operations.
Common Policies
This section includes some common policies you might want to use in your organization.
Note
Where to create the policy: In the tenancy, because users reside in the tenancy.
Allow group HelpDesk to manage users in tenancy
l The operation to list IAM policies includes the contents of the policies themselves
l The list operations for Networking resource-types return all the information (for
example, the contents of security lists and route tables)
l The operation to list instances requires the read verb instead of inspect, and the
contents include the user-provided metadata.
l The operation to view Audit service events requires the read verb instead of inspect.
Where to create the policy: In the tenancy. Because of the concept of policy inheritance,
auditors can then inspect both the tenancy and all compartments beneath it. Or you could
choose to give auditors access to only specific compartments if they don't need access to the
entire tenancy.
Allow group Auditors to inspect all-resources in tenancy
Where to create the policy: In the tenancy. Because of the concept of policy inheritance,
NetworkAdmins can then manage a cloud network in any compartment. To reduce the scope
of access to a particular compartment, specify that compartment instead of the tenancy.
Allow group NetworkAdmins to manage virtual-network-family in tenancy
Where to create the policy: In the tenancy. Because of the concept of policy inheritance,
NetworkAdmins can then manage load balancers in any compartment. To reduce the scope of
access to a particular compartment, specify that compartment instead of the tenancy.
Allow group NetworkAdmins to manage load-balancers in tenancy
If the group uses the Console to manage load balancers, an additional policy to use the
associated networking resources is required:
Allow group NetworkAdmins to manage load-balancers in tenancy
If a particular group needs to update existing load balancers (for example, modify the
backend set) but not create or delete them, use this statement:
Allow group LBUsers to use load-balancers in tenancy
Where to create the policy: The easiest approach is to put this policy in the tenancy. If you
want the admins of the individual compartments (ABC and XYZ) to have control over the
individual policy statements for their compartments, see Policy Attachment.
Allow group InstanceLaunchers to manage instance-family in compartment ABC
Where to create the policy: In the tenancy, so that the access is easily granted to all
compartments by way of policy inheritance. To reduce the scope of access to just the
dedicated virtual machine hosts and instances in a particular compartment, specify that
compartment instead of the tenancy.
Allow group DedicatedVMHostAdmins to manage dedicated-vm-hosts in tenancy
Where to create the policy: In the tenancy, so that the access is easily granted to all
compartments by way of policy inheritance. To reduce the scope of access to just the
dedicated virtual machine hosts and instances in a particular compartment, specify that
compartment instead of the tenancy.
Allow group DedicatedVMHostAdmins to use dedicated-vm-hosts in tenancy
Where to create the policy: In the tenancy, so that the access is easily granted to all
compartments by way of policy inheritance. To reduce the scope of access to just the instance
configurations, instance pools, and cluster networks in a particular compartment, specify that
compartment instead of the tenancy.
Allow group InstancePoolAdmins to manage compute-management-family in tenancy
If a group needs to create instance configurations using existing instances as a template, and
uses the API, SDKs, or command line interface (CLI) to do this, add the following statements
to the policy:
Allow group InstancePoolAdmins to read instance-family in tenancy
If a particular group needs to start, stop, or reset the instances in existing instance pools, but
not create or delete instance pools, use this statement:
Allow group InstancePoolUsers to use instance-pools in tenancy
Where to create the policy: In the tenancy, so that the access is easily granted to all
compartments by way of policy inheritance. To reduce the scope of access to just the
autoscaling configurations in a particular compartment, specify that compartment instead of
the tenancy.
Allow group AutoscalingAdmins to manage auto-scaling-configurations in tenancy
Let users list and subscribe to images from the Partner Image catalog
Type of access: Ability to list and create subscriptions to images in the Partner Image
catalog. It does not include the ability to create instances using images from the Partner
Image catalog (see Let users launch Compute instances).
Where to create the policy: In the tenancy. To reduce the scope of access to just creating
subscriptions in a particular compartment, specify that compartment instead of the tenancy in
the third statement.
Allow group CatalogSubscribers to inspect app-catalog-listing in tenancy
Let volume admins manage block volumes, backups, and volume groups
Type of access: Ability to do all things with block storage volumes, volume backups, and
volume groups in all compartments with the exception of copying volume backups across
regions. This makes sense if you want to have a single set of volume admins manage all the
volumes, volume backups, and volume groups in all the compartments. The second statement
is required in order to attach/detach the volumes from instances.
Where to create the policy: In the tenancy, so that the access is easily granted to all
compartments by way of policy inheritance. To reduce the scope of access to just the
volumes/backups and instances in a particular compartment, specify that compartment
instead of the tenancy.
Allow group VolumeAdmins to manage volume-family in tenancy
If the group needs to also copy volume backups and boot volume backups across regions, add
the following statements to the policy:
Allow group VolumeAdmins to use volume-backups in tenancy where request.permission='VOLUME_BACKUP_COPY'
Allow group VolumeAdmins to use boot-volume-backups in tenancy where request.permission='BOOT_VOLUME_
BACKUP_COPY'
volumes themselves. This makes sense if you want to have a single set of volume backup
admins manage all the volume backups in all the compartments. The first statement gives the
required access to the volume that is being backed up; the second statement enables creation
of the backup (and the ability to delete backups). The third statement enables the creation and
management of user defined backup policies; the fourth statement enables assignment and
removal of assignment of backup policies.
Where to create the policy: In the tenancy, so that the access is easily granted to all
compartments by way of policy inheritance. To reduce the scope of access to just the volumes
and backups in a particular compartment, specify that compartment instead of the tenancy.
Allow group VolumeBackupAdmins to use volumes in tenancy
If the group will be using the Console, the following policy gives a better user experience:
Allow group VolumeBackupAdmins to use volumes in tenancy
The last two statements are not necessary in order to manage volume backups. However,
they enable the Console to display all the information about a particular volume and the
available backup policies.
manage boot volumes themselves. This makes sense if you want to have a single set of boot
volume backup admins manage all the boot volume backups in all the compartments. The first
statement gives the required access to the boot volume that is being backed up; the second
statement enables creation of the backup (and the ability to delete backups). The third
statement enables the creation and management of user defined backup policies; the fourth
statement enables assignment and removal of assignment of backup policies.
Where to create the policy: In the tenancy, so that the access is easily granted to all
compartments by way of policy inheritance. To reduce the scope of access to just the boot
volumes and backups in a particular compartment, specify that compartment instead of the
tenancy.
Allow group BootVolumeBackupAdmins to use volumes in tenancy
If the group will be using the Console, the following policy gives a better user experience:
Allow group BootVolumeBackupAdmins to use volumes in tenancy
The last two statements are not necessary in order to manage volume backups. However,
they enable the Console to display all the information about a particular boot volume and the
available backup policies.
Where to create the policy: In the tenancy, so that the access is easily granted to all
compartments by way of policy inheritance. To reduce the scope of access to just the volumes
and volume groups in a particular compartment, specify that compartment instead of the
tenancy.
Allow group VolumeGroupCreators to inspect volumes in tenancy
Allow group VolumeGroupCreators to manage volume-groups in tenancy
Where to create the policy: In the tenancy, so that the access is easily granted to all
compartments by way of policy inheritance. To reduce the scope of access to just the volumes
and volume groups in a particular compartment, specify that compartment instead of the
tenancy.
Allow group VolumeGroupCloners to inspect volumes in tenancy
Allow group VolumeGroupCloners to manage volume-groups in tenancy
Allow group VolumeGroupCloners to manage volumes in tenancy
Where to create the policy: In the tenancy, so that the access is easily granted to all
compartments by way of policy inheritance. To reduce the scope of access to just the
volumes/backups and volume groups/volume group backups in a particular compartment,
specify that compartment instead of the tenancy.
Allow group VolumeGroupBackupAdmins to inspect volume-groups in tenancy
Allow group VolumeGroupBackupAdmins to manage volumes in tenancy
Allow group VolumeGroupBackupAdmins to manage volume-group-backups in tenancy
Allow group VolumeGroupBackupAdmins to manage volume-backups in tenancy
Where to create the policy: In the tenancy, so that the access is easily granted to all
compartments by way of policy inheritance. To reduce the scope of access to just the
volumes/backups and volume groups/volume group backups in a particular compartment,
specify that compartment instead of the tenancy.
Allow group VolumeGroupBackupAdmins to inspect volume-group-backups in tenancy
Allow group VolumeGroupBackupAdmins to read volume-backups in tenancy
Allow group VolumeGroupBackupAdmins to manage volume-groups in tenancy
Allow group VolumeGroupBackupAdmins to manage volumes in tenancy
Where to create the policy: In the tenancy, so that the ability to create, manage, or delete
a file system is easily granted to all compartments by way of policy inheritance. To reduce the
scope of these administrative functions to file systems in a particular compartment, specify
that compartment instead of the tenancy.
Allow group StorageAdmins to manage file-family in tenancy
Where to create the policy: In the tenancy, so that the ability to create a file system is
easily granted to all compartments by way of policy inheritance. To reduce the scope of these
administrative functions to file systems in a particular compartment, specify that
compartment instead of the tenancy.
The second statement is required when users create a file system using the Console. It
enables the Console to display a list of mount targets that the new file system can be
associated with.
Where to create the policy: In the tenancy, so that the access is easily granted to all
compartments by way of policy inheritance. To reduce the scope of access to just the buckets
and objects in a particular compartment, specify that compartment instead of the tenancy.
Allow group ObjectAdmins to manage buckets in tenancy
Where to create the policy: The easiest approach is to put this policy in the tenancy. If you
want the admins of compartment ABC to have control over the policy, see Policy Attachment.
Allow group ObjectWriters to read buckets in compartment ABC
Allow group ObjectWriters to manage objects in compartment ABC where any {request.permission='OBJECT_
CREATE', request.permission='OBJECT_INSPECT'}
Allow group ObjectWriters to manage objects in compartment ABC where all {target.bucket.name='BucketA',
any {request.permission='OBJECT_CREATE', request.permission='OBJECT_INSPECT'}}
For more information about using conditions, see Advanced Policy Features.
Where to create the policy: The easiest approach is to put this policy in the tenancy. If you
want the admins of compartment ABC to have control over the policy, see Policy Attachment.
Allow group ObjectReaders to read buckets in compartment ABC
For more information about using conditions, see Advanced Policy Features.
This makes sense if you want to have a single set of database admins manage all the bare
metal, virtual machine, and Exadata DB systems in all the compartments.
Where to create the policy: In the tenancy, so that the access is easily granted to all
compartments by way of policy inheritance. To reduce the scope of access to just the
database systems in a particular compartment, specify that compartment instead of the
tenancy.
Allow group DatabaseAdmins to manage database-family in tenancy
Where to create the policy: In the tenancy, so that the access is easily granted to all
compartments by way of policy inheritance. To reduce the scope of access to just the Exadata
Cloud@Customer
Where to create the policy: In the tenancy, so that the access is easily granted to all
compartments by way of policy inheritance. To reduce the scope of access to just the
Autonomous Databases databases in a particular compartment, specify that compartment
instead of the tenancy.
Example 1: For fleet admins. Allows Autonomous Database fleet administrator access to
both workload types (Autonomous Data Warehouse and Autonomous Transaction
Processing), and to dedicated Exadata infrastructure resources (container databases and
Autonomous Exadata Infrastructure instances).
Allow group DatabaseAdmins to manage autonomous-database-family in tenancy
If you need to restrict access to the Autonomous Exadata Infrastructure and Autonomous
Container Database resource types (applicable only to dedicated Exadata infrastructure
systems), you can do so by creating separate policy statements for database administrators
that allow access to only Autonomous Databases and their backups. Because a policy
statement can only specify one resource type, you will need to create separate statements for
the database and backup resources.
To reduce the scope of access to either the Autonomous Data Warehouse or Autonomous
Transaction Processing workload types, use a where clause, as in the following examples:
Example 4: For Autonomous Data Warehouse admins. Limits Autonomous Database access
to Autonomous Data Warehouse databases and backups.
Allow group ADB-Admins to manage autonomous-database in tenancy where target.workloadType = 'DW'
Where to create the policy: In the tenancy, so that access is easily granted to all
compartments by way of policy inheritance. To reduce the scope of access to just the vaults,
keys, and secret components in a particular compartment, specify that compartment instead
of the tenancy.
Allow group SecurityAdmins to manage vaults in tenancy
Where to create the policy: The easiest approach is to put this policy in the tenancy. If you
want the admins of the individual compartment (ABC) to have control over the individual
policy statements for their compartment, see Policy Attachment.
Allow group SecurityAdmins to manage keys in compartment ABC where target.vault.id='<vault_OCID>'
Where to create the policy: The easiest approach is to put this policy in the tenancy. If you
want the admins of the individual compartment (ABC) to have control over the individual
policy statements for their compartment, see Policy Attachment.
Allow group SecurityAdmins to use keys in compartment ABC where target.key.id='<key_OCID>'
l Create or update an encrypted bucket, volume, or file system and to encrypt or decrypt
data in the bucket, volume, or file system.
l Create Kubernetes clusters with encrypted Kubernetes secrets at rest in the etcd key-
value store.
l Create a stream pool to encrypt data in the streams in the stream pool.
This policy requires that you also have a companion policy that lets Object Storage, Block
Volume, File Storage, Container Engine for Kubernetes, or Streaming use the key to perform
cryptographic operations.
Where to create the policy: The easiest approach is to put this policy in the tenancy. If you
want the admins of the individual compartment (ABC) to have control over the individual
policy statements for their compartment, see Policy Attachment.
Allow group ObjectWriters, VolumeWriters, FileWriters, ClusterWriters, StreamWriters to use key-delegate
in compartment ABC where target.key.id = '<key_OCID>'
Let Block Volume, Object Storage, File Storage, Container Engine for
Kubernetes, and Streaming services encrypt and decrypt volumes, volume
backups, buckets, file systems, Kubernetes secrets, and stream pools
Type of access: Ability to list, view, and perform cryptographic operations with all keys in
compartment ABC. Because Object Storage is a regional service, it has regional endpoints. As
such, you must specify the regional service name for each region where you’re using Object
Storage with Vault encryption. This policy also requires that you have a companion policy that
allows a user group to use the delegated key that Object Storage, Block Volume, File Storage,
Where to create the policy: The easiest approach is to put this policy in the tenancy. If you
want the admins of the individual compartment (ABC) to have control over the individual
policy statements for their compartment, see Policy Attachment.
Allow service blockstorage, objectstorage-<region_name>, FssOc1Prod, oke, streaming to use keys in
compartment ABC where target.key.id = '<key_OCID>'
For Object Storage, replace <region_name> with the appropriate region identifier, for
example:
l objectstorage-us-phoenix-1
l objectstorage-us-ashburn-1
l objectstorage-eu-frankfurt-1
l objectstorage-uk-london-1
l objectstorage-ap-tokyo-1
To determine the region name value of an Oracle Cloud Infrastructure region, see Regions and
Availability Domains.
For File Storage, the service name used in the policy is FssOc1Prod.
For Container Engine for Kubernetes, the service name used in the policy is oke.
Where to create the policy: The easiest approach is to put this policy in the tenancy. If you
want the admins of the individual compartment (ABC) to have control over the individual
policy statements for their compartment, see Policy Attachment.
Allow group SecurityAdmins to manage secret-family in compartment ABC where target.vault.id='<vault_
OCID>'
Where to create the policy: In the tenancy, so that access is easily granted to all
compartments by way of policy inheritance. To reduce the scope of access to just the vaults,
keys, and secrets in a particular compartment, specify that compartment instead of the
tenancy.
Allow group SecretsUsers to use secret-family in tenancy
The first two statements let GroupAdmins list all the users and groups in the tenancy, list
which users are in a particular group, and list what groups a particular user is in.
The last two statements together let GroupAdmins change a group's membership. The
condition at the end of the last two statements lets GroupAdmins manage membership to all
groups except the Administrators group (see The Administrators Group and Policy). You
should protect membership to that group because it has power to do anything throughout the
tenancy.
It might seem that the last two statements should also cover the basic listing functionality that
the first two statements enable. To better understand how conditions work and why you also
need the first two statements, see Variables that Aren't Applicable to a Request Result in a
Declined Request.
Where to create the policy: In the tenancy, because users and groups reside in the
tenancy.
Allow group GroupAdmins to inspect users in tenancy
The preceding policy allows PHX-Admins to manage all aspects of all resources in US West
(Phoenix).
Members of the PHX-Admins group can only manage IAM resources if the tenancy's home
region is US West (Phoenix).
Where to create the policy: In the tenancy, so that the access is easily granted to all
compartments by way of policy inheritance. To reduce the scope of access to just the streams
in a particular compartment, specify that compartment instead of the tenancy.
Allow group StreamAdmins to manage streams in tenancy
Where to create the policy: In the tenancy, so that the access is easily granted to all
compartments by way of policy inheritance. To reduce the scope of access to just the streams
in a particular compartment, specify that compartment instead of the tenancy.
Allow group StreamUsers to use stream-push in tenancy
Where to create the policy: In the tenancy, so that the access is easily granted to all
compartments by way of policy inheritance. To reduce the scope of access to just the streams
in a particular compartment, specify that compartment instead of the tenancy.
allow group StreamUsers to use stream-pull in tenancy where target.stream.id = '<stream_OCID>'
Where to create the policy: In the tenancy, so that the access is easily granted to all
compartments by way of policy inheritance. To reduce the scope of access to just the streams
in a particular compartment, specify that compartment instead of the tenancy.
Allow group StreamUsers to use stream-pull in tenancy
Where to create the policy: In the tenancy, so that the access is easily granted to all
compartments by way of policy inheritance. To reduce the scope of access to just the metric
definitions in a particular compartment, specify that compartment instead of the tenancy.
Allow group MetricReaders to inspect metrics in compartment ABC
Where to create the policy: In the tenancy, so that the access is easily granted to all
compartments by way of policy inheritance. To reduce the scope of access to just the metrics
in a particular compartment, specify that compartment instead of the tenancy.
Allow group MetricReaders to read metrics in compartment ABC
Where to create the policy: In the tenancy, so that the access is easily granted to all
compartments by way of policy inheritance. To reduce the scope of access to the specified
metric namespace to just within a particular compartment, specify that compartment instead
of the tenancy.
Allow group MetricReaders to read metrics in compartment ABC where target.metrics.namespace='oci_
computeagent'
The preceding policy allows MetricReaders to view and retrieve metric data points from all
monitoring-enabledCompute instances in the ABC compartment.
Where to create the policy: In the tenancy, so that the access is easily granted to all
compartments by way of policy inheritance. To reduce the scope of access to just metrics in a
particular compartment, specify that compartment instead of the tenancy.
Allow group MetricPublishers to use metrics in tenancy where
target.metrics.namespace='mycustomnamespace'
The preceding policy allows MetricPublishers to publish data points for the custom metric
namespace mycustomnamespace in the tenancy.
Let instances make API calls to access monitoring metrics in the tenancy
Type of access: Ability to call the Monitoring API for access to monitoring metrics. The
instances on which API requests originate must be members of the dynamic group indicated in
the policy. For more information, see Calling Services from an Instance and Metrics Feature
Overview.
The preceding policy allows applications that are running on Compute instances in the
dynamic group MetricInstances to send API requests to the Monitoring service in the
tenancy.
Where to create the policy: In the tenancy. Because of the concept of policy inheritance,
AlarmUsers can then view alarms in any compartment. To reduce the scope of access to a
particular compartment, specify that compartment instead of the tenancy.
Where to create the policy: In the tenancy. Because of the concept of policy inheritance,
AlarmUsers can then view and create alarms in any compartment. To reduce the scope of
access to a particular compartment, specify that compartment instead of the tenancy.
Allow group AlarmUsers to manage alarms in tenancy
Where to create the policy: In the tenancy. Because of the concept of policy inheritance,
AlarmUsers can then view and create alarms in any compartment. To reduce the scope of
access to a particular compartment, specify that compartment instead of the tenancy.
Allow group AlarmUsers to manage alarms in tenancy
Where to create the policy: This is a special cross-tenancy policy and must be created in
the tenancy. For more information, see Cost and Usage Reports Overview.
define tenancy usage-report as
ocid1.tenancy.oc1..aaaaaaaaned4fkpkisbwjlr56u7cj63lf3wffbilvqknstgtvzub7vhqkggq
endorse group Administrators to read objects in tenancy usage-report
Where to create the policy: In the tenancy so that users in the <Example_Group> can see
costs for the entire account.
Allow group <Example_Group> to read usage-reports in tenancy
This line gives the user inspect access to resources in compartments to select actions.
allow group <RuleAdmins> to inspect compartments in tenancy
This line gives the user access to defined tags to apply filter tags to rules.
allow group <RuleAdmins> to use tag-namespaces in tenancy
These lines give the user access to Streaming resources for actions
allow group <RuleAdmins> to inspect streams in tenancy
allow group <RuleAdmins> to use stream-push in tenancy
allow group <RuleAdmins> to use stream-pull in tenancy
These lines give the user access to Functions resources for actions.
allow group <RuleAdmins> to use virtual-network-family in tenancy
allow group <RuleAdmins> to manage function-family in tenancy
This line give the user access to Notifications topics for actions.
allow group <RuleAdmins> to use ons-topic in tenancy
This line gives the user manage access to rules for Events.
allow group <RuleAdmins> to manage cloudevents-rules in tenancy
Conditions
As part of a policy statement, you can specify one or more conditions that must be met in
order for access to be granted. For a simple example, see Let group admins manage group
membership.
Each condition consists of one or more predefined variables that you specify values for in the
policy statement. Later, when someone requests access to the resource in question, if the
condition in the policy is met, it evaluates to true and the request is allowed. If the condition is
not met, it evaluates to false and the request is not allowed.
There are two types of variables: those that are relevant to the request itself, and those
relevant to the resource being acted upon in the request, also known as the target. The name
of the variable is prefixed accordingly with either request or target followed by a period. For
example, there's a request variable called request.operation to represent the API operation
being requested. This variable lets you write a broad policy statement, but add a condition
based on the specific API operation. For an example, see Let users write objects to Object
Storage buckets.
Important
If the variable is not applicable to the incoming request, the condition evaluates to false and
the request is declined. For example, here are the basic policy statements that together let
someone add or remove users from any group except Administrators:
Allow group GroupAdmins to use users in tenancy
where target.group.name != 'Administrators'
Given the above policy, if GroupAdmins tried to call a general API operation for users such as
ListUsers or UpdateUser (which lets you change the user's description), the request would
be declined, even though those API operations are covered by use users.This is because the
above policy statement for use users also includes the target.group.name variable, but the
ListUsers or UpdateUser request doesn't involve specifying a group. There is no
target.group.name for those requests, so the request is declined.
If you want to also grant access to general user API operations that don't involve a particular
group, you would need an additional statement that gives the level of access you want to
grant, but without the condition. For example, if you want to grant access to ListUsers, you
need this additional statement:
Allow group GroupAdmins to inspect users in tenancy
Or if you want to grant access to UpdateUser, you need this additional statement (which also
covers ListUsers because the use verb includes the capabilities of the inspect verb):
Allow group GroupAdmins to use users in tenancy
This general concept also applies to groups (e.g., ListGroups and UpdateGroup), and any
other resource type with target variables.
For more information about the syntax of conditions, see Conditions. For a list of all the
variables you can use in policies, see the tables in the Policy Reference.
Using conditions and a set of tag variables, you can write policy to scope access based on the
tags that have been applied to a resource. Access can be controlled based on a tag that exists
on the requesting resource (the group or dynamic group in the policy) or on the target of the
request (resource or compartment). Tag-based access control provides additional flexibility to
your policies by allowing you to define access that spans compartments, groups, and
resources. For details about how to write policies to scope access by tags, see Using Tags to
Manage Access.
Permissions
Permissions are the atomic units of authorization that control a user's ability to perform
operations on resources. Oracle defines all the permissions in the policy language. When you
write a policy giving a group access to a particular verb and resource-type, you're actually
giving that group access to one or more predefined permissions. The purposes of verbs is to
simplify the process of granting multiple related permissions that cover a broad set of access
or a particular operational scenario. The next sections give more details and examples.
Relation to Verbs
To understand the relationship between permissions and verbs, let's look at an example. A
policy statement that allows a group to inspect volumes actually gives the group access to a
permission called VOLUME_INSPECT (permissions are always written with all capital letters
and underscores). In general, that permission enables the user to get information about block
volumes.
As you go from inspect > read > use > manage, the level of access generally increases, and
the permissions granted are cumulative. The following table shows the permissions included
with each verb for the volumes resource-type. Notice that no additional permissions are
granted going from inspect to read.
VOLUME_UPDATE VOLUME_UPDATE
VOLUME_WRITE VOLUME_WRITE
VOLUME_CREATE
VOLUME_DELETE
The policy reference lists the permissions covered by each verb for each given resource-type.
For example, for block volumes and other resources covered by the Core Services, see the
tables in Details for Verb + Resource-Type Combinations. The left column of each of those
tables lists the permissions covered by each verb. The other sections of the policy reference
include the same kind of information for the other services.
Each API operation requires the caller to have access to one or more permissions. For
example, to use either ListVolumes or GetVolume, you must have access to a single
permission: VOLUME_INSPECT. To attach a volume to an instance, you must have access to
multiple permissions, some of which are related to the volumes resource-type, some to the
volume-attachments resource-type, and some related to the instances resource-type:
l VOLUME_WRITE
l VOLUME_ATTACHMENT_CREATE
l INSTANCE_ATTACH_VOLUME
The policy reference lists which permissions are required for each API operation. For
example, for the Core Services API operations, see the table in Permissions Required for Each
API Operation.
The policy language is designed to let you write simple statements involving only verbs and
resource-types, without having to state the desired permissions in the statement. However,
there may be situations where a security team member or auditor wants to understand the
specific permissions a particular user has. The tables in the policy reference show each verb
and the associated permissions. You can look at the groups the user is in and the policies
applicable to those groups, and from there compile a list of the permissions granted.
However, having a list of the permissions isn't the complete picture. Conditions in a policy
statement can scope a user's access beyond individual permissions (see the next section).
Also, each policy statement specifies a particular compartment and can have conditions that
further scope the access to only certain resources in that compartment.
In a policy statement, you can use conditions combined with permissions or API operations to
reduce the scope of access granted by a particular verb.
For example, let's say you want group XYZ to be able to list, get, create, or update groups
(i.e., change their description), but not delete them. To list, get, create, and update groups,
you need a policy with manage groups as the verb and resource-type. According to the table
in Details for Verbs + Resource-Type Combinations, the permissions covered are:
l GROUP_INSPECT
l GROUP_UPDATE
l GROUP_CREATE
l GROUP_DELETE
To restrict access to only the desired permissions, you could add a condition that explicitly
states the permissions you want to allow:
Allow group XYZ to manage groups in tenancy
However, with this approach, be aware that any new permissions the service might add in the
future would automatically be granted to group XYZ. Only GROUP_DELETE would be omitted.
Another alternative would be to write a condition based on the specific API operations. Notice
that according to the table in Permissions Required for Each API Operation, both ListGroups
and GetGroup require only the GROUP_INSPECT permission. Here's the policy:
Allow group XYZ to manage groups in tenancy
It can be beneficial to use permissions instead of API operations in conditions. In the future, if
a new API operation is added that requires one of the permissions listed in the permissions-
based policy above, that policy will already control XYZ group's access to that new API
operation.
But notice that you can further scope a user's access to a permission by also specifying a
condition based on API operation. For example, you could give a user access to GROUP_
INSPECT, but then only to ListGroups.
Allow group XYZ to manage groups in tenancy
You can scope access to only a set of allowed IP addresses. For example, you can write policy
to allow only requests from a given public IP range to access a specific Object Storage bucket;
or, you can allow only specific subnets of a specific VCN to make requests over a service
gateway.
1. Create a network source object that specifies the allowed IP addresses. See Managing
Network Sources for details.
2. Write a policy that uses the network source object in a condition.
For example:
allow group GroupA to manage object-family in tenancy where request.networkSource.name='corpnet'
Policy Syntax
The overall syntax of a policy statement is as follows:
For limits on the number of policies and statements, see Service Limits.
Subject
Specify one or more comma-separated groups by name or OCID. Or specify any-user to
cover all users in the tenancy.
Examples:
id ocid1.group.oc1..aaaaaaaaqjihfhvxmum...awuc7i5xwe6s7qmnsbc6a
l To specify multiple groups by OCID (the OCIDs are shortened for brevity):
Allow group
id ocid1.group.oc1..aaaaaaaaqjihfhvxmumrl...wuc7i5xwe6s7qmnsbc6a,
id ocid1.group.oc1..aaaaaaaavhea5mellwzb...66yfxvl462tdgx2oecyq
Verb
Specify a single verb. For a list of verbs, see Verbs. Example:
Allow group A-Admins to manage all-resources in compartment Project-A
Resource-Type
Specify a single resource-type, which can be one of the following:
A family resource-type covers a variety of components that are typically used together. This
makes it easier to write a policy that gives someone access to work with various aspects of
your cloud network.
Examples:
Location
Specify a single compartment or compartment path by name or OCID. Or simply specify
tenancy to cover the entire tenancy. Remember that users, groups, and compartments reside
in the tenancy. Policies can reside in (i.e., be attached to) either the tenancy or a child
compartment.
Note
The location is required in the statement. If you want to attach a policy to a compartment, you
must be in that compartment when you create the policy. For more information, see Policy
Attachment.
To specify a compartment that is not a direct child of the compartment you are attaching the
policy to, specify the path to the compartment, using the colon (:) as a separator. For more
information, see Policies and Compartment Hierarchies.
Examples:
Allow group id
ocd1.group.oc1..aaaaaaaavhea5mell...b4rm66yfxvl462tdgx2oecyq
to manage all-resources in compartment id
ocid1.compartment.oc1..aaaaaaaaphfjutov5s...vyypllbtctehnqg756a
l To specify a compartment that is not a direct child of the compartment where you are
attaching the policy, specify the path:
Allow group InstanceAdmins to manage instance-family in compartment Project-A:Project-A2
Conditions
Specify one or more conditions. Use any or all with multiple conditions for a logical OR or
AND, respectively.
Important
For a list of variables supported by all the services, see General Variables for All Requests.
Also see the details for each service in the Policy Reference. Here are the types of values you
can use in conditions:
Type Examples
String '[email protected]'
'ocid1.compartment.oc1..aaaaaaaaph...ctehnqg756a'
Examples:
Note
l A single condition.
The following policy enables the GroupAdmins group to create, update, or delete any
groups with names that start with "A-Users-":
Allow group GroupAdmins to manage groups in tenancy where target.group.name = /A-Users-*/
Allow group GroupAdmins to inspect groups in tenancy
The following policy enables the GroupAdmins group to manage the membership of any
group besides the Administrators group. (Note that you must include separate
statements for inspectaccess because the target.group.name variable is not used by
the ListUsers and ListGroups operations):
Allow group GroupAdmins to inspect users in tenancy
The following policy enables the NetworkAdmins group to manage cloud networks in any
compartment except the one specified:
Allow group NetworkAdmins to manage virtual-network-family in tenancy where target.compartment.id
!= 'ocid1.compartment.oc1..aaaaaaaayzfqeibduyox6icmdol6zyar3ugly4fmameq4h7lcdlihrvur7xq'
l Multiple conditions.
The following policy lets GroupAdmins create, update, or delete any groups whose
names start with "A-", except for the A-Admins group itself:
Policy Reference
This reference includes:
For instructions on how to create and manage policies using the Console or API, see Managing
Policies.
Verbs
The verbs are listed in order of least amount of ability to most. The exact meaning of a each
verb depends on which resource-type it's paired with. The tables later in this section show the
API operations covered by each combination of verb and resource-type.
use Includes read plus the ability to work with existing resources Day-to-day
(the actions vary by resource type). Includes the ability to end users of
update the resource, except for resource-types where the resources
"update" operation has the same effective impact as the
"create" operation (e.g., UpdatePolicy,
UpdateSecurityList, etc.), in which case the "update"
ability is available only with the manage verb. In general, this
verb does not include the ability to create or delete that type
of resource.
Resource-Types
The family resource-types are listed below. For the individual resource-types that make up
each family, follow the links.
IAM has no family resource-type, only individual ones. See Details for IAM.
where
request.user.mfaTotpVerified
='true'
Note: target.compartment.id
and target.compartment.name
cannot be used with a "List" API
operation to filter the list based
on the requesting user's access to
the compartment.
Resource-Types
l announcements
Supported Variables
Only the general variables are supported (see General Variables for All Requests).
The following tables show the permissions and API operations covered by each verb. The level
of access is cumulative as you go from inspect > read > use > manage. A plus sign (+) in a
table cell indicates incremental access compared to the cell directly above it, whereas "no
extra" indicates no incremental access.
For example, the read verb for the announcements resource-type includes the same
permissions and API operations as the inspect verb, plus the ANNOUNCEMENT_READ
permission and an additional API peration, GetAnnouncement. However, the use verb and
manage verbs cover no extra permissions or API operations compared to read.
announcements
INSPECT
READ
ANNOUNCEMENT_READ GetAnnouncement
USE
MANAGE
The following table lists the API operations in a logical order, grouped by resource type.
ListAnnouncements ANNOUNCEMENT_LIST
GetAnnouncement ANNOUNCEMENT_READ
Resource-Types
api-gateway-family
l api-gateways
l api-deployments
l api-workrequests
COMMENTS
A policy that uses <verb> api-gateway-family is equivalent to writing one with a separate
<verb> <individual resource-type> statement for each of the individual resource-types.
See the table in Details for Verb + Resource-Type Combinations for a detailed breakout of the
API operations covered by each verb, for each individual resource-type included in api-
gateway-family.
Supported Variables
API Gateway supports all the general variables (see General Variables for All Requests).
The following tables show the permissions and API operations covered by each verb. The level
of access is cumulative as you go from inspect > read > use > manage. A plus sign (+) in a
table cell indicates incremental access compared to the cell directly above it, whereas "no
extra" indicates no incremental access..
For example, the read verb for the api-gateways resource-type includes the same
permissions and API operations as the inspect verb, plus the API_GATEWAY_READ
permission and a number of API operations (e.g., GetGateway, etc.). The use verb covers
additional permissions and API operations compared to read. Lastly, manage covers more
permissions and operations compared to use.
api-gateways
INSPECT
READ
USE
deployments)
MANAGE
API_GATEWAY_CREATE CreateGateway
API_GATEWAY_DELETE DeleteGateway
API_GATEWAY_UPDATE UpdateGateway
API_GATEWAY_MOVE ChangeGatewayCompartment
api-deployments
INSPECT
READ
API_DEPLOYMENT_READ gateways)
USE
API_DEPLOYMENT_UPDATE gateways)
MANAGE
API_DEPLOYMENT_DELETE
API_DEPLOYMENT_MOVE
api-workrequests
INSPECT
READ
API_WORK_REQUEST_READ GetWorkRequest
ListWorkRequestErrors
ListWorkRequestLogs
USE
API_WORK_REQUEST_CANCEL CancelWorkRequest
MANAGE
The following table lists the API operations in a logical order, grouped by resource type. For
information about permissions, see Permissions.
ListGateways API_GATEWAY_LIST
CreateGateway API_GATEWAY_CREATE
GetGateway API_GATEWAY_READ
UpdateGateway API_GATEWAY_UPDATE
DeleteGateway API_GATEWAY_DELETE
ListDeployments API_DEPLOYMENT_LIST
ListWorkRequests API_WORK_REQUEST_LIST
GetWorkRequest API_WORK_REQUEST_READ
CancelWorkRequest API_WORK_REQUEST_CANCEL
ListWorkRequestErrors API_WORK_REQUEST_READ
ListWorkRequestLogs API_WORK_REQUEST_READ
Resource-Types
audit-events
Supported Variables
Only the general variables are supported (see General Variables for All Requests).
The following tables show the permissions and API operations covered by each verb. The level
of access is cumulative as you go from inspect > read > use > manage. A plus sign (+) in a
table cell indicates incremental access compared to the cell directly above it, whereas "no
extra" indicates no incremental access.
For example, the use and manage verbs for the audit-events resource-type cover no extra
permissions or API operations compared to the read verb.
AUDIT -EVENTS
INSPECT
READ
USE
MANAGE
The following table lists the API operations in a logical order, grouped by resource type.
ListEvents AUDIT_EVENT_READ
Resource-Types
Networking
AGGREGATE RESOURCE-TYPE
virtual-network-family
INDIVIDUAL RESOURCE-TYPES
vcns
subnets
route-tables
network-security-groups
security-lists
dhcp-options
private-ips
public-ips
ipv6s
internet-gateways
nat-gateways
service-gateways
drgs
drg-attachments
cpes
ipsec-connections
cross-connects
cross-connect-groups
virtual-circuits
vnics
vnic-attachments
vlans
COMMENTS
See the table in Details for Verb + Resource-Type Combinations for a detailed breakout of the
API operations covered by each verb, for each individual resource-type included in virtual-
network-family.
Compute
app-catalog-listing
console-histories
instances
instance-console-connection
instance-images
instance-configurations
instance-pools
cluster-networks
auto-scaling-configurations
work-requests
dedicated-vm-hosts
COMMENTS
See the table in Details for Verb + Resource-Type Combinations for a detailed breakout of the
API operations covered by each verb, for each individual resource-type.
Block Volume
AGGREGATE RESOURCE-TYPE
volume-family
INDIVIDUAL RESOURCE-TYPES
volumes
volume-attachments
volume-backups
boot-volume-backups
backup-policies
backup-policy-assignments
volume-groups
volume-group-backups
COMMENTS
A policy that uses <verb> volume-family is equivalent to writing one with a separate
<verb> <individual resource-type> statement for each of the individual resource-
types.
See the table in Details for Verb + Resource-Type Combinations for a detailed breakout of
the API operations covered by each verb, for each individual resource-type included in
volume-family.
Supported Variables
The Core Services support all the general variables, plus the ones listed here. For more
information about general variables supported by Oracle Cloud Infrastructure services, see
General Variables for All Requests.
target.boot- String Use this variable to control whether Compute instances can be
volume.kms- launched with boot volumes that were created without a Vault
key.id service master encryption key.
The following tables show the permissions and API operations covered by each verb. The level
of access is cumulative as you go from inspect > read > use > manage. A plus sign (+) in a
table cell indicates incremental access compared to the cell directly above it, whereas "no
extra" indicates no incremental access.
For example, the read and use verbs for the vcns resource-type cover no extra permissions
or API operations compared to the inspect verb. However, the manage verb includes several
extra permissions and API operations.
vcns
INSPECT
manage vcns)
network-family.
READ
USE
MANAGE
USE + USE +
VCN_ATTACH CreateVcn
VCN_DETACH UpdateVcn
VCN_UPDATE DeleteVcn
VCN_CREATE ChangeVcnCompartment
VCN_DELETE
VCN_MOVE
subnets
INSPECT
GetSubnet
READ
USE
SUBNET_DETACH instance-family)
volume is attached)
family)
MANAGE
SUBNET_MOVE dhcp-options)
family.
route-tables
INSPECT
GetRouteTable
READ
USE
MANAGE
ROUTE_TABLE_DELETE
use service-gateways)
ROUTE_TABLE_MOVE
UpdateRouteTable (also need manage
use service-gateways)
options)
manage subnets)
network-family.
network-security-groups
INSPECT
and
UpdateNetworkSecurityGroupSecurityRul
security-groups)
READ
NETWORK_SECURITY_GROUP_READ GetNetworkSecurityGroup
ListNetworkSecurityGroups
USE
MEMBERS catalog-listing)
MANAGE
SECURITY_RULES RemoveNetworkSecurityGroupSecurityRul
virtual-network-family.
es
security-lists
INSPECT
GetSecurityList
READ
USE
MANAGE
SECURITY_LIST_UPDATE available only with the manage verb, not the CreateSubnet, DeleteSubnet (both also
SECURITY_LIST_MOVE options)
manage subnets)
network-family.
dhcp-options
INSPECT
GetDhcpOptions
READ
USE
MANAGE
DHCP_DETACH Note: Ability to update a set of DHCP options is (both also need manage vcns)
DHCP_UPDATE available only with the manage verb, not the CreateSubnet, DeleteSubnet (also need
network-family.
private-ips
INSPECT
GetPrivateIp
ListPublicIps,
GetPublicIpByPrivateIpId,
GetPublicIpByIpAddress
READ
USE
PRIVATE_IP_UPDATE For ephemeral public IPs: UpdatePublicIp, also need use subnets and use vnics)
network-family.
MANAGE
use service-gateways)
use service-gateways)
network-family.
public-ips
INSPECT
READ
ListPublicIps,
GetPublicIpByPrivateIpId,
GetPublicIpByIpAddress
permissions.
USE
manage public-ips).
network-family.
MANAGE
network-family.
ipv6s
INSPECT
READ
subnets)
family.
USE
MANAGE
network-family.
internet-gateways
INSPECT
GetInternetGateway
READ
USE
MANAGE
INTERNET_GATEWAY_UPDATE is available only with the manage verb, not the CreateRouteTable, DeleteRouteTable
service-gateways)
network-family.
nat-gateways
INSPECT
READ
GetNatGateway
USE
network-family.
MANAGE
NAT_GATEWAY_CREATE ChangeNatGatewayCompartment Note: All of the above operations in this cell are
NAT_GATEWAY_DELETE Note: Ability to update a NAT gateway is totally covered with just manage virtual-
NAT_GATEWAY_MOVE available only with the manage verb, not the network-family.
use verb.
service-gateways
INSPECT
GetServiceGateway
READ
USE
gateways)
MANAGE
SERVICE_GATEWAY_ADD_SERVICE Note: Ability to update a service gateway is route-tables if you associate a route table
SERVICE_GATEWAY_DELETE_SERVICE available only with the manage verb, not the during the update)
SERVICE_GATEWAY_MOVE use verb. DeleteServiceGateway (also need manage
vcns)
network-family.
local-peering-gateways
INSPECT
GetLocalPeeringGateway
READ
USE
MANAGE
LOCAL_PEERING_GATEWAY_DETACH creation)
LOCAL_PEERING_GATEWAY_CREATE UpdateLocalPeeringGateway (also need
LOCAL_PEERING_GATEWAY_DELETE manage route-tables if you associate a
LOCAL_PEERING_GATEWAY_MOVE
route table during the update)
manage vcns)
CreateRouteTable, DeleteRouteTable
service-gateways)
service-gateways)
ChangeLocalPeeringGatewayCompartment
network-family.
local-peering-from
INSPECT
READ
USE
MANAGE
Region).)
family.
local-peering-to
INSPECT
READ
USE
MANAGE
Region).)
family.
remote-peering-connections
INSPECT
GetRemotePeeringConnection
READ
USE
MANAGE
REMOTE_PEERING_CONNECTION_DELETE ChangeRemotePeeringConnectionCompartm
REMOTE_PEERING_CONNECTION_ ent
network-family.
remote-peering-from
INSPECT
READ
USE
MANAGE
family.
remote-peering-to
INSPECT
READ
USE
MANAGE
Regions).)
family.
drgs
INSPECT
DRG_ATTACHMENT_READ GetDrg
ListDrgAttachments
READ
USE
MANAGE
USE + USE +
DRG_ATTACH CreateDrg
DRG_DETACH UpdateDrg
DRG_UPDATE DeleteDrg
DRG_ATTACHMENT_UPDATE ChangeDrgCompartment
DRG_CREATE
DRG_DELETE
DRG_MOVE
cpes
INSPECT
GetCpe
READ
USE
MANAGE
CPE_UPDATE DeleteCpe
drgs)
CPE_CREATE ChangeCpeCompartment
Note: All of the above operations in this cell are
CPE_DELETE totally covered with just manage virtual-
CPE_RESOURCE_MOVE
network-family.
ipsec
INSPECT
GetIPSecConnection
GetIPSecConnectionStatus
ListIPSecConnectionTunnels
GetIPSecConnectionTunnel
GetTunnelCpeDeviceConfig
GetTunnelCpeDeviceTemplateContent
GetCpeDeviceTemplateContent
GetIpsecCpeDeviceTemplateContent
READ
IPSEC_CONNECTION_DEVICE_CONFIG_READ GetIPSecConnectionDeviceConfig
GetIPSecConnectionTunnelSharedSecret
USE
MANAGE
IPSEC_CONNECTION_DELETE UpdateIPSecConnectionTunnel Note: All of the above operations in this cell are
UPDATE network-family.
cross-connects
INSPECT
GetCrossConnect
READ
USE
MANAGE
CROSS_CONNECT_RESOURCE_MOVE virtual-circuits)
CROSS_CONNECT_ATTACH
CROSS_CONNECT_DETACH
cross-connect-groups
INSPECT
GetCrossConnectGroup
READ
USE
MANAGE
CROSS_CONNECT_GROUP_UPDATE CreateCrossConnectGroup
CROSS_CONNECT_GROUP_CREATE DeleteCrossConnectGroup
CROSS_CONNECT_GROUP_DELETE ChangeCrossConnectGroupCompartment
CROSS_CONNECT_GROUP_RESOURCE_MOVE
virtual-circuits
INSPECT
GetVirtualCircuit
READ
USE
connects)
MANAGE
VIRTUAL_CIRCUIT_CREATE CreateVirtualCircuit,
connects)
network-family.
vnics
INSPECT
CreateInstanceConfigurationFromInstan
attachments.)
READ
USE
ips)
MANAGE
vnic-attachments
INSPECT
instances)
CreateInstanceConfigurationFromInstan
attachments.)
READ
USE
MANAGE
vlans
INSPECT
GetVlan
READ
USE
no extra
MANAGE
GROUP family.
VLAN_MOVE
The instance-family aggregate resource-type includes extra permissions beyond the sum of
the permissions for the individual resource-types included in instance-family. For example:
It includes a few permissions for vnics and volumes, even though those resource-types
aren't generally considered part of the instance-family. Why are there extras included? So
you can write fewer policy statements to cover general use cases, like working with an
instance that has an attached block volume. You can write one statement for instance-
family instead of multiple statements covering instances, vnics, and volumes.
l VNIC_READ
l VNIC_ATTACHMENT_READ
l VOLUME_ATTACHMENT_INSPECT
l VOLUME_ATTACHMENT_READ
l VNIC_ATTACH
l VNIC_DETACH
l VOLUME_ATTACHMENT_UPDATE
l VOLUME_ATTACHMENT_CREATE
l VOLUME_ATTACHMENT_DELETE
The following tables list the permissions and API operations covered by each of the individual
resource-types included in instance-family.
instances
INSPECT
inspect console-histories)
vnic-attachments)
attachments)
attachments)
READ
images)
CreateInstanceConfigurationFromInstan
attachments.)
USE
MANAGE
volume is attached)
GetWorkRequest, ListWorkRequestErrors,
LaunchInstance)
console-histories
INSPECT
instances)
READ
USE
MANAGE
instance-console-connection
INSPECT
instances)
READ
read instances)
USE
MANAGE
INSTANCE_CONSOLE_CONNECTION_DELETE
instance-images
INSPECT
GetImage
READ
use network-security-groups)
histories)
USE
INSTANCE_IMAGE_UPDATE
MANAGE
for CreateImage)
app-catalog-listing
INSPECT
READ
groups)
MANAGE
APP_CATALOG_LISTING_SUBSCRIBE CreateAppCatalogSubscription
DeleteAppCatalogSubscription
The following tables list the permissions and API operations covered by each of the individual
resource-types included in compute-management-family.
instance-configurations
INSPECT
READ
INSTANCE_CONFIGURATION_READ GetInstanceConfiguration
USE
MANAGE
INSTANCE_CONFIGURATION_UPDATE CreateInstanceConfigurationDetails
INSTANCE_CONFIGURATION_LAUNCH subtype)
INSTANCE_CONFIGURATION_DELETE UpdateInstanceConfiguration
INSTANCE_CONFIGURATION_MOVE LaunchInstanceConfiguration
DeleteInstanceConfiguration
ChangeInstanceConfigurationCompartmen
instance-pools
INSPECT
READ
INSTANCE_POOL_READ GetInstancePool
ListInstancePoolInstances
USE
INSTANCE_POOL_POWER_ACTIONS SoftresetInstancePool
StartInstancePool
StopInstancePool
MANAGE
volumes)
GetWorkRequest, ListWorkRequestErrors,
CreateInstancePool or
cluster-networks
INSPECT
READ
USE
MANAGE
CLUSTER_NETWORK_MOVE subnets)
GetWorkRequest, ListWorkRequestErrors,
for CreateClusterNetwork or
TerminateClusterNetwork, depending on
The following tables list the permissions and API operations covered by other Compute
resource-types that aren't included in any aggregate resource-types.
auto-scaling-configurations
INSPECT
ListAutoScalingPolicies
READ
AUTO_SCALING_CONFIGURATION_READ GetAutoScalingConfiguration
GetAutoScalingPolicy
USE
MANAGE
AUTO_SCALING_CONFIGURATION_DELETE DeleteAutoScalingConfiguration
AUTO_SCALING_CONFIGURATION_MOVE CreateAutoScalingPolicy
UpdateAutoScalingPolicy
DeleteAutoScalingPolicy
dedicated-vm-hosts
INSPECT
READ
DEDICATED_VM_HOST_READ GetDedicatedVmHost
ListDedicatedVmHostInstances
USE
machine host.
MANAGE
DEDICATED_VM_HOST_MOVE DeleteDedicatedVmHost
DEDICATED_VM_HOST_DELETE ChangeDedicatedVmHostCompartment
work-requests
INSPECT
READ
USE
MANAGE
The following tables list the permissions and API operations covered by each of the individual
resource-types included in volume-family.
volumes
INSPECT
volume-backups)
volume-backups)
is required.
CreateInstanceConfigurationFromInstan
attachments.)
READ
USE
instances)
volume-backups)
MANAGE
When moving volumes between service master encryption key, also need use
compartments, the move volume permission is key-delegate (for the caller) and read keys
needed for both source and destination (for the service principal). For more
volume-attachments
INSPECT
attachments.
CreateInstanceConfigurationFromInstan
READ
USE
VOLUME_ATTACHMENT_UPDATE
MANAGE
volume-backups
INSPECT
READ
USE
VOLUME_BACKUP_UPDATE volumes)
MANAGE
VOLUME_BACKUP_CREATE When moving volume backups between CreateVolumeBackup (also need use
VOLUME_BACKUP_MOVE permission is needed for both source and DeleteVolumeBackup (also need inspect
boot-volume-backups
INSPECT
inspect volumes)
READ
USE
MANAGE
BOOT_VOLUME_BACKUP_CREATE When moving boot volume backups between CreateBootVolumeBackup (also need use
BOOT_VOLUME_BACKUP_MOVE backup permission is needed for both source DeleteBootVolumeBackup (also need
backup-policies
INSPECT
GetVolumeBackupPolicy
READ
USE
BACKUP_POLICIES_UPDATE UpdateVolumeBackupPolicy
MANAGE
BACKUP_POLICIES_CREATE CreateVolumeBackupPolicy
BACKUP_POLICIES_DELETE DeleteVolumeBackupPolicy
backup-policy-assignments
INSPECT
READ
USE
MANAGE
BACKUP_POLICY_ASSIGNMENT_CREATE CreateVolumeBackupPolicyAssignment
BACKUP_POLICY_ASSIGNMENT_DELETE DeleteVolumeBackupPolicyAssignment
volume-groups
INSPECT
GetVolumeGroup
READ
USE
MANAGE
USE + USE +
VOLUME_GROUP_UPDATE DeleteVolumeGroup
VOLUME_GROUP_CREATE
VOLUME_GROUP_DELETE
VOLUME_GROUP_MOVE
volume-group-backups
INSPECT
GetVolumeGroupBackup
READ
USE
MANAGE
VOLUME_GROUP_BACKUP_CREATE following:
VOLUME_GROUP_BACKUP_DELETE
VOLUME_GROUP_BACKUP_MOVE
l inspect volume
group for the source
volume group
l create volume
group backup
volume backup
ChangeVolumeGroupBackupCompartment
request)
destination compartments.
The following tables list the API operations grouped by resource type. The resource types are
listed in alphabetical order.
CreateVolumeBackupPolicy BACKUP_POLICIES_CREATE
DeleteVolumeBackupPolicy BACKUP_POLICIES_DELETE
GetVolumeBackupPolicy BACKUP_POLICIES_INSPECT
ListVolumeBackupPolicies BACKUP_POLICIES_INSPECT
CreateVolumeBackupPolicyAssignment BACKUP_POLICY_ASSIGNMENT_CREATE
DeleteVolumeBackupPolicyAssignment BACKUP_POLICY_ASSIGNMENT_DELETE
GetVolumeBackupPolicyAssignment BACKUP_POLICY_ASSIGNMENT_INSPECT
UpdateClusterNetwork CLUSTER_NETWORK_UPDATE
ChangeClusterNetworkCompartment CLUSTER_NETWORK_MOVE
DeleteConsoleHistory CONSOLE_HISTORY_DELETE
ListCpes CPE_READ
GetCpe CPE_READ
UpdateCpe CPE_UPDATE
CreateCpe CPE_CREATE
DeleteCpe CPE_DELETE
ChangeCpeCompartment CPE_RESOURCE_MOVE
UpdateTunnelCpeDeviceConfig IPSEC_CONNECTION_UPDATE
GetTunnelCpeDeviceConfig IPSEC_CONNECTION_READ
GetTunnelCpeDeviceTemplateContent IPSEC_CONNECTION_READ
GetCpeDeviceTemplateContent IPSEC_CONNECTION_READ
GetIpsecCpeDeviceTemplateContent IPSEC_CONNECTION_READ
ListCrossConnects CROSS_CONNECT_READ
GetCrossConnect CROSS_CONNECT_READ
UpdateCrossConnect CROSS_CONNECT_UPDATE
ChangeCrossConnectCompartment CROSS_CONNECT_RESOURCE_MOVE
ListCrossConnectGroups CROSS_CONNECT_GROUP_READ
GetCrossConnectGroup CROSS_CONNECT_GROUP_READ
UpdateCrossConnectGroup CROSS_CONNECT_GROUP_UPDATE
CreateCrossConnectGroup CROSS_CONNECT_GROUP_CREATE
DeleteCrossConnectGroup CROSS_CONNECT_GROUP_DELETE
ChangeCrossConnectGroupCompartment CROSS_CONNECT_GROUP_RESOURCE_MOVE
ListDhcpOptions DHCP_READ
GetDhcpOptions DHCP_READ
UpdateDhcpOptions DHCP_UPDATE
ChangeDhcpOptionsCompartment DHCP_MOVE
ListDrgs DRG_READ
GetDrg DRG_READ
UpdateDrg DRG_UPDATE
CreateDrg DRG_CREATE
DeleteDrg DRG_DELETE
ChangeDrgCompartment DRG_MOVE
ListDrgAttachments DRG_ATTACHMENT_READ
GetDrgAttachment DRG_ATTACHMENT_READ
UpdateDrgAttachment DRG_ATTACHMENT_UPDATE
ROUTE_TABLE_ATTACH is necessary to
associate a route table with the DRG
attachment during the update.
ROUTE_TABLE_ATTACH is necessary to
associate a route table with the DRG
attachment during creation.
CreateInstanceConsoleConnection INSTANCE_CONSOLE_CONNECTION_CREATE
and INSTANCE_READ
DeleteInstanceConsoleConnection INSTANCE_CONSOLE_CONNECTION_DELETE
ListInstanceConsoleConnections INSTANCE_CONSOLE_CONNECTION_INSPECT
and INSTANCE_INSPECT and INSTANCE_READ
ListImages INSTANCE_IMAGE_READ
GetImage INSTANCE_IMAGE_READ
UpdateImage INSTANCE_IMAGE_UPDATE
ChangeImageCompartment INSTANCE_IMAGE_MOVE
DeleteImage INSTANCE_IMAGE_DELETE
ListInstances INSTANCE_READ
GetInstance INSTANCE_READ
UpdateInstance INSTANCE_UPDATE
InstanceAction INSTANCE_POWER_ACTIONS
ChangeInstanceCompartment INSTANCE_MOVE
ListInstanceConfigurations INSTANCE_CONFIGURATION_INSPECT
GetInstanceConfiguration INSTANCE_CONFIGURATION_READ
LaunchInstanceConfiguration INSTANCE_CONFIGURATION_LAUNCH
UpdateInstanceConfiguration INSTANCE_CONFIGURATION_UPDATE
ChangeInstanceConfigurationCompart INSTANCE_CONFIGURATION_MOVE
ment
DeleteInstanceConfiguration INSTANCE_CONFIGURATION_DELETE
ListInstancePools INSTANCE_POOL_INSPECT
ListInstancePoolInstances INSTANCE_POOL_READ
GetInstancePool INSTANCE_POOL_READ
UpdateInstancePool INSTANCE_POOL_UPDATE
ResetInstancePool INSTANCE_POOL_POWER_ACTIONS
SoftresetInstancePool INSTANCE_POOL_POWER_ACTIONS
StartInstancePool INSTANCE_POOL_POWER_ACTIONS
StopInstancePool INSTANCE_POOL_POWER_ACTIONS
ChangeInstancePoolCompartment INSTANCE_POOL_MOVE
ListInternetGateways INTERNET_GATEWAY_READ
GetInternetGateway INTERNET_GATEWAY_READ
UpdateInternetGateway INTERNET_GATEWAY_UPDATE
ChangeInternetGatewayCompartment INTERNET_GATEWAY_MOVE
ListIPSecConnections IPSEC_CONNECTION_READ
GetIPSecConnection IPSEC_CONNECTION_READ
UpdateIpSecConnection IPSEC_CONNECTION_UPDATE
GetIPSecConnectionDeviceConfig IPSEC_CONNECTION_DEVICE_CONFIG_READ
GetIPSecConnectionDeviceStatus IPSEC_CONNECTION_READ
ListIPSecConnectionTunnels IPSEC_CONNECTION_READ
GetIPSecConnectionTunnel IPSEC_CONNECTION_READ
UpdateIPSecConnectionTunnel IPSEC_CONNECTION_UPDATE
GetIPSecConnectionTunnelSharedSecr IPSEC_CONNECTION_DEVICE_CONFIG_READ
et
UpdateIPSecConnectionTunnelSharedS IPSEC_CONNECTION_DEVICE_CONFIG_UPDATE
ecret
GetIpv6 IPV6_READ
ListLocalPeeringGateways LOCAL_PEERING_GATEWAY_READ
GetLocalPeeringGateway LOCAL_PEERING_GATEWAY_READ
UpdateLocalPeeringGateway LOCAL_PEERING_GATEWAY_UPDATE
ROUTE_TABLE_ATTACH is necessary to
associate a route table with the LPG during the
update.
ROUTE_TABLE_ATTACH is necessary to
associate a route table with the LPG during
creation.
ConnectLocalPeeringGateway LOCAL_PEERING_GATEWAY_CONNECT_FROM
and
LOCAL_PEERING_GATEWAY_CONNECT_TO
ChangeLocalPeeringGatewayCompartme LOCAL_PEERING_GATEWAY_MOVE
nt
ListNatGateways NAT_GATEWAY_READ
GetNatGateway NAT_GATEWAY_READ
UpdateNatGateway NAT_GATEWAY_UPDATE
ChangeNatGatewayCompartment NAT_GATEWAY_MOVE
ListNetworkSecurityGroups NETWORK_SECURITY_GROUP_READ
GetNetworkSecurityGroup NETWORK_SECURITY_GROUP_READ
UpdateNetworkSecurityGroup NETWORK_SECURITY_GROUP_UPDATE
ChangeNetworkSecurityGroupCompartm NETWORK_SECURITY_GROUP_MOVE
ent
ListNetworkSecurityGroupSecurityRu NETWORK_SECURITY_GROUP_LIST_SECURITY_
les RULES
UpdateNetworkSecurityGroupSecurity NETWORK_SECURITY_GROUP_UPDATE_
Rules SECURITY_RULES and
NETWORK_SECURITY_GROUP_INSPECT if
writing a rule that specifies a network security
group as the source (for ingress rules) or
destination (for egress rules)
AddNetworkSecurityGroupSecurityRul NETWORK_SECURITY_GROUP_UPDATE_
es SECURITY_RULES and
NETWORK_SECURITY_GROUP_INSPECT if
writing a rule that specifies a network security
group as the source (for ingress rules) or
destination (for egress rules)
RemoveNetworkSecurityGroupSecurity NETWORK_SECURITY_GROUP_UPDATE_
Rules SECURITY_RULES
ListPrivateIps PRIVATE_IP_READ
GetPrivateIp PRIVATE_IP_READ
ListRemotePeeringConnections REMOTE_PEERING_CONNECTION_READ
GetRemotePeeringConnection REMOTE_PEERING_CONNECTION_READ
UpdateRemotePeeringConnection REMOTE_PEERING_CONNECTION_UPDATE
ChangeRemotePeeringConnectionCompa REMOTE_PEERING_CONNECTION_RESOURCE_
rtment MOVE
ConnectRemotePeeringConnections REMOTE_PEERING_CONNECTION_CONNECT_
FROM and
REMOTE_PEERING_CONNECTION_CONNECT_TO
ChangePublicIpCompartment PUBLIC_IP_MOVE
ListRouteTables ROUTE_TABLE_READ
GetRouteTable ROUTE_TABLE_READ
PRIVATE_IP_ROUTE_TABLE_ATTACH (if
creating a route rule that uses a private IP as a
target) and
PRIVATE_IP_ROUTE_TABLE_DETACH (if
deleting a route rule that uses a private IP as a
target) and
LOCAL_PEERING_GATEWAY_ATTACH (if
creating a route rule that uses an LPG as a
target) and
LOCAL_PEERING_GATEWAY_DETACH (if
deleting a route rule that uses an LPG as a
target) and
PRIVATE_IP_ROUTE_TABLE_ATTACH (if
creating a route rule that uses a private IP as a
target) and
LOCAL_PEERING_GATEWAY_ATTACH (if
creating a route rule that uses an LPG as a
target) and
PRIVATE_IP_ROUTE_TABLE_DETACH (if
deleting a route rule that uses a private IP as a
target) and
LOCAL_PEERING_GATEWAY_DETACH (if
deleting a route rule that uses an LPG as a
target) and
ChangeRouteTableCompartment ROUTE_TABLE_MOVE
ListSecurityLists SECURITY_LIST_READ
GetSecurityList SECURITY_LIST_READ
UpdateSecurityList SECURITY_LIST_UPDATE
ChangeSecurityListCompartment SECURITY_LIST_MOVE
ListServiceGateways SERVICE_GATEWAY_READ
GetServiceGateway SERVICE_GATEWAY_READ
UpdateServiceGateway SERVICE_GATEWAY_UPDATE
ROUTE_TABLE_ATTACH is necessary to
associate a route table with the service
gateway during the update.
ChangeServiceGatewayCompartment SERVICE_GATEWAY_MOVE
ROUTE_TABLE_ATTACH is necessary to
associate a route table with the service
gateway during creation.
AttachServiceId SERVICE_GATEWAY_ADD_SERVICE
DetachServiceId SERVICE_GATEWAY_DELETE_SERVICE
ListShapes INSTANCE_INSPECT
ListSubnets SUBNET_READ
GetSubnet SUBNET_READ
UpdateSubnet SUBNET_UPDATE
ChangeSubnetCompartment SUBNET_MOVE
ListVcns VCN_READ
GetVcn VCN_READ
UpdateVcn VCN_UPDATE
CreateVcn VCN_CREATE
DeleteVcn VCN_DELETE
ChangeVcnCompartment VCN_MOVE
ListVirtualCircuits VIRTUAL_CIRCUIT_READ
GetVirtualCircuit VIRTUAL_CIRCUIT_READ
changeVirtualCircuitCompartment VIRTUAL_CIRCUIT_RESOURCE_MOVE
ListVlans VLAN_READ
GetVlan VLAN_READ
UpdateVlan VLAN_UPDATE
ChangeVlanCompartment VLAN_MOVE
GetVnic VNIC_READ
UpdateVnic VNIC_UPDATE
GetVnicAttachment VNIC_ATTACHMENT_READ
ListVolumes VOLUME_INSPECT
GetVolume VOLUME_INSPECT
UpdateVolume VOLUME_UPDATE
DeleteVolume VOLUME_DELETE
ChangeVolumeCompartment VOLUME_MOVE
ChangeVolumeBackupCompartment VOLUME_BACKUP_MOVE
GetBootVolume VOLUME_INSPECT
ListBootVolumes VOLUME_INSPECT
UpdateBootVolume VOLUME_UPDATE
DeleteBootVolume VOLUME_DELETE
ChangeBootVolumeCompartment BOOT_VOLUME_MOVE
ChangeBootVolumeBackupCompartment BOOT_VOLUME_BACKUP_MOVE
VOLUME_GROUP_CREATE, VOLUME_GROUP_
INSPECT, VOLUME_CREATE, VOLUME_WRITE if
cloning a volume group.
VOLUME_GROUP_CREATE, VOLUME_GROUP_
BACKUP_INSPECT, VOLUME_BACKUP_
READ/BOOT_VOLUME_BACKUP_READ,
VOLUME_CREATE, VOLUME_WRITE if restoring
from a volume group backup.
DeleteVolumeGroup VOLUME_GROUP_DELETE
GetVolumeGroup VOLUME_GROUP_INSPECT
ListVolumeGroups VOLUME_GROUP_INSPECT
GetVolumeGroupBackup VOLUME_GROUP_BACKUP_INSPECT
ListVolumeGroupBackups VOLUME_GROUP_BACKUP_INSPECT
UpdateVolumeGroupBackup VOLUME_GROUP_BACKUP_UPDATE
CreateDedicatedVmHost DEDICATED_VM_HOST_CREATE
ChangeDedicatedVmHostCompartment DEDICATED_VM_HOST_MOVE
DeleteDedicatedVmHost DEDICATED_VM_HOST_DELETE
GetDedicatedVmHost DEDICATED_VM_HOST_READ
ListDedicatedVmHosts DEDICATED_VM_HOST_INSPECT
ListDedicatedVmHostInstances DEDICATED_VM_HOST_READ
ListDedicatedVmHostInstanceShapes None
ListDedicatedVmHostShapes None
LaunchInstance DEDICATED_VM_HOST_LAUNCH_INSTANCE in
dedicated virtual machine host compartment
ListAutoScalingConfigurations AUTO_SCALING_CONFIGURATION_
INSPECT
GetAutoScalingConfiguration AUTO_SCALING_CONFIGURATION_
READ
UpdateAutoScalingConfiguration AUTO_SCALING_CONFIGURATION_
UPDATE and INSTANCE_POOL_UPDATE
CreateAutoScalingConfiguration AUTO_SCALING_CONFIGURATION_
CREATE and INSTANCE_POOL_UPDATE
ChangeAutoScalingConfigurationCompartment AUTO_SCALING_CONFIGURATION_
MOVE
DeleteAutoScalingConfiguration AUTO_SCALING_CONFIGURATION_
DELETE and INSTANCE_POOL_UPDATE
ListAutoScalingPolicies AUTO_SCALING_CONFIGURATION_
READ
GetAutoScalingPolicy AUTO_SCALING_CONFIGURATION_
READ
UpdateAutoScalingPolicy AUTO_SCALING_CONFIGURATION_
UPDATE and INSTANCE_POOL_UPDATE
CreateAutoScalingPolicy AUTO_SCALING_CONFIGURATION_
CREATE and INSTANCE_POOL_UPDATE
DeleteAutoScalingPolicy AUTO_SCALING_CONFIGURATION_
DELETE and INSTANCE_POOL_UPDATE
ListWorkRequests WORKREQUEST_INSPECT
Resource-Types
l cluster-family
l clusters
l cluster-node-pools
l cluster-work-requests
COMMENTS
A policy that uses <verb> cluster-family is equivalent to writing one with a separate
<verb> <individual resource-type> statement for each of the individual resource-types.
See the table in Details for Verb + Resource-Type Combinations for a detailed breakout of the
API operations covered by each verb, for each individual resource-type included in cluster-
family.
Supported Variables
Container Engine for Kubernetes supports all the general variables (see General Variables for
All Requests), plus the ones listed here.
The following tables show the permissions and API operations covered by each verb. The level
of access is cumulative as you go from inspect > read > use > manage. A plus sign (+) in a
table cell indicates incremental access compared to the cell directly above it, whereas "no
extra" indicates no incremental access.
For example, the read verb for the clusters resource-type includes the same permissions
and API operations as the inspect verb, plus the CLUSTER_READ permission and a number of
API operations (e.g., GetCluster, etc.). The use verb covers still another permission and API
operation compared to read. Lastly, manage covers more permissions and operations
compared to use.
clusters
INSPECT
ListWorkRequests
READ
CLUSTER_READ GetCluster
GetWorkRequest
ListWorkRequestErrors
ListWorkRequestLogs
USE
CLUSTER_USE GetClusterKubeconfig
MANAGE
cluster-node-pools
INSPECT
ListWorkRequests
READ
CLUSTER_NODE_POOL_READ GetNodePool
GetWorkRequest
ListWorkRequestErrors
ListWorkRequestLogs
USE
MANAGE
cluster-work-requests
INSPECT
READ
CLUSTER_WORK_REQUEST_READ GetWorkRequest
ListWorkRequestErrors
ListWorkRequestLogs
USE
MANAGE
CLUSTER_WORK_REQUEST_DELETE DeleteWorkRequest
The following table lists the API operations in a logical order, grouped by resource type. For
information about permissions, see Permissions.
ListClusters CLUSTER_INSPECT
CreateCluster CLUSTER_CREATE
GetClusterKubeconfig CLUSTER_USE
GetCluster CLUSTER_READ
UpdateCluster CLUSTER_UPDATE
AdministerK8s CLUSTER_MANAGE
ListNodePools CLUSTER_NODE_POOL_INSPECT
CreateNodePool CLUSTER_NODE_POOL_CREATE
GetNodePool CLUSTER_NODE_POOL_READ
GetNodePoolOptions CLUSTER_READ
UpdateNodePool CLUSTER_NODE_POOL_UPDATE
DeleteNodePool CLUSTER_NODE_POOL_DELETE
DeleteWorkRequest CLUSTER_WORK_REQUEST_DELETE
Tip
Resource-Types
An aggregate resource-type covers the list of individual resource-types that directly follow.
For example, writing one policy to allow a group to have access to the autonomous-
database-family is equivalent to writing four separate policies for the group that would grant
access to the autonomous-databases, autonomous-backups, autonomous-container-
databases, and autonomous-exadata-infrastructures resource-types. For more
information, see Resource-Types.
AGGREGATE RESOURCE-TYPE
autonomous-database-family
INDIVIDUAL RESOURCE-TYPES :
autonomous-databases
autonomous-backups
autonomous-container-databases
autonomous-exadata-infrastructures
Supported Variables
Only the general variables are supported (see General Variables for All Requests).
The following tables show the permissions and API operations covered by each verb. The level
of access is cumulative as you go from inspect > read > use > manage. A plus sign (+) in a
table cell indicates incremental access compared to the cell directly above it, whereas "no
extra" indicates no incremental access.
For example, the read verb for the autonomous-databases resource-type covers the same
permissions and API operations as the inspect verb, plus the AUTONOMOUS_DATABASE_
CONTENT_READ permission. The read verb partially covers the
CreateAutonomousDatabaseBackup operation, which also needs manage permissions for
autonomous-backups.
Note
autonomous-databases
INSPECT
AUTONOMOUS_DATABASE_INSPECT GetAutonomousDatabase,
ListAutonomousDatabases
READ
USE
AUTONOMOUS_DATABASE_UPDATE ChangeAutonomousDatabaseCompartment
MANAGE
AUTONOMOUS_DATABASE_CREATE
AUTONOMOUS_DATABASE_DELETE
autonomous-backups
INSPECT
GetAutonomousDatabaseBackup
READ
ChangeAutonomousDatabaseCompartment
USE
MANAGE
AUTONOMOUS_DB_BACKUP_DELETE
autonomous-container-databases
INSPECT
INSPECT GetAutonomousContainerDatabase
READ
USE
artment
MANAGE
AUTONOMOUS_CONTAINER_DATABASE_ TerminateAutonomousContainerDatabase
AUTONOMOUS_CONTAINER_DATABASE_ infrastructure)
DELETE
autonomous-exadata-infrastructures
INSPECT
INSPECT GetAutonomousExadataInfrastructure
READ
no extra
USE
container-databases)
MANAGE
AUTONOMOUS_EXADATA_INFRASTRUCTURE_ e,
CREATE TerminateAutonomousExadataInfrastruct
DELETE subnets)
Note
The autonomous-data-warehouse-family
permissions are deprecated. You can use the resource
family autonomous-database-family to grant access
to the Autonomous Database resources used by both
Autonomous Data Warehouse databases and
Autonomous Transaction Processing databases.
autonomous-data-warehouses
INSPECT
ListAutonomousDataWarehouses
READ
warehouse-backups)
USE
MANAGE
AUTONOMOUS_DW_CREATE DeleteAutonomousDataWarehouse
AUTONOMOUS_DW_DELETE
autonomous-data-warehouse-backups
INSPECT
GetAutonomousDataWarehouseBackup
READ
warehouses)
USE
MANAGE
READ + CreateAutonomousDataWarehouseBackup
warehouses)
The following tables list the API operations for Autonomous Database resources in a logical
order, grouped by resource type.
ListAutonomousExadataInfrastructures AUTONOMOUS_EXADATA_
INFRASTRUCTURE_INSPECT
LaunchAutonomousExadataInfrastructure AUTONOMOUS_EXADATA_
INFRASTRUCTURE_CREATE and
VNIC_CREATE and SUBNET_
ATTACH and VNIC_ATTACH
GetAutonomousExadataInfrastructure AUTONOMOUS_EXADATA_
INFRASTRUCTURE_INSPECT
TerminateAutonomousExadataInfrastructure AUTONOMOUS_EXADATA_
INFRASTRUCTURE_DELETE and
VNIC_DELETE and SUBNET_
DETACH and VNIC_DETACH
UpdateAutonomousExadataInfrastructure AUTONOMOUS_EXADATA_
INFRASTRUCTURE_UPDATE
and AUTONOMOUS_DB_
SYSTEM_INSPECT
ChangeAutonomousExadataInfrastructureCompartment AUTONOMOUS_EXADATA_
INFRASTRUCTURE_INSPECT
and AUTONOMOUS_EXADATA_
INFRASTRUCTURE_UPDATE
ListAutonomousContainerDatabases AUTONOMOUS_CONTAINER_
DATABASE_INSPECT
GetAutonomousContainerDatabase AUTONOMOUS_CONTAINER_
DATABASE_INSPECT
CreateAutonomousContainerDatabase AUTONOMOUS_EXADATA_
INFRASTRUCTURE_UPDATE
and AUTONOMOUS_
CONTAINER_DATABASE_
CREATE
TerminateAutonomousContainerDatabase AUTONOMOUS_EXADATA_
INFRASTRUCTURE_UPDATE
and AUTONOMOUS_
CONTAINER_DATABASE_
DELETE
UpdateAutonomousContainerDatabase AUTONOMOUS_CONTAINER_
DATABASE_UPDATE
ChangeAutonomousContainerDatabaseCompartment AUTONOMOUS_CONTAINER_
DATABASE_INSPECT and
AUTONOMOUS_CONTAINER_
DATABASE_UPDATE
GetAutonomousDatabase AUTONOMOUS_DATABASE_
INSPECT
ListAutonomousDatabases AUTONOMOUS_DATABASE_
INSPECT
CreateAutonomousDatabase AUTONOMOUS_DATABASE_
CREATE
l In the compartment of
the new Autonomous
Database: VNIC_CREATE
and VNIC_DELETE and
NETWORK_SECURITY_
GROUP_UPDATE_
MEMBERS and VNIC_
ASSOCIATE_NETWORK_
SECURITY_GROUP
l In the compartment of
the specified
subnet: SUBNET_ATTACH
and SUBNET_DETACH
UpdateAutonomousDatabase AUTONOMOUS_DATABASE_
UPDATE
l VNIC_UPDATE and
NETWORK_SECURITY_
GROUP_UPDATE_
MEMBERS and VNIC_
ASSOCIATE_NETWORK_
SECURITY_GROUP
ChangeAutonomousDatabaseCompartment AUTONOMOUS_DATABASE_
UPDATE and AUTONOMOUS_
DB_BACKUP_INSPECT and
AUTONOMOUS_DB_BACKUP_
CONTENT_READ and
AUTONOMOUS_DATABASE_
CONTENT_WRITE
DeleteAutonomousDatabase AUTONOMOUS_DATABASE_
DELETE
l In the compartment of
the new Autonomous
Database: VNIC_DELETE
and NETWORK_
SECURITY_GROUP_
UPDATE_MEMBERS
l In the compartment of
the configured subnet:
SUBNET_DETACH
StartAutonomousDatabase AUTONOMOUS_DATABASE_
UPDATE
StopAutonomousDatabase AUTONOMOUS_DATABASE_
UPDATE
RestoreAutonomousDatabase AUTONOMOUS_DB_BACKUP_
CONTENT_READ and
AUTONOMOUS_DATABASE_
CONTENT_WRITE
CreateAutonomousDatabaseBackup AUTONOMOUS_DB_BACKUP_
CREATE and AUTONOMOUS_
DATABASE_CONTENT_READ
DeleteAutonomousDatabaseBackup AUTONOMOUS_DB_BACKUP_
DELETE
ListAutonomousDatabaseBackups AUTONOMOUS_DB_BACKUP_
INSPECT
GetAutonomousDatabaseBackup AUTONOMOUS_DB_BACKUP_
INSPECT
GetAutonomousDataWarehouse AUTONOMOUS_DW_INSPECT
ListAutonomousDataWarehouses AUTONOMOUS_DW_INSPECT
CreateAutonomousDataWarehouse AUTONOMOUS_DW_CREATE
UpdateAutonomousDataWarehouse AUTONOMOUS_DW_UPDATE
DeleteAutonomousDataWarehouse AUTONOMOUS_DW_DELETE
StartAutonomousDataWarehouse AUTONOMOUS_DW_UPDATE
StopAutonomousDataWarehouse AUTONOMOUS_DW_UPDATE
RestoreAutonomousDataWarehouse AUTONOMOUS_DW_BACKUP_CONTENT_READ
and AUTONOMOUS_DW_CONTENT_WRITE
ListAutonomousDataWarehouseBackups AUTONOMOUS_DW_BACKUP_INSPECT
GetAutonomousDataWarehouseBackup AUTONOMOUS_DW_BACKUP_INSPECT
Policy Details for Bare Metal, Virtual Machine, and Exadata DB Systems
This topic covers details for writing policies to control access to bare metal, virtual machine,
and Exadata DB system resources.
Tip
Resource-Types
An aggregate resource-type covers the list of individual resource-types that directly follow.
For example, writing one policy to allow a group to have access to the database-family is
equivalent to writing five separate policies for the group that would grant access to the db-
systems, db-nodes, db-homes, databases, and backups resource-types. For more
information, see Resource-Types.
RESOURCE -TYPES FOR BARE METAL, VIRTUAL MACHINE , AND EXADATA DB S YSTEMS
AGGREGATE RESOURCE-TYPE
database-family
INDIVIDUAL RESOURCE-TYPES :
db-systems
db-nodes
db-homes
databases
backups
Supported Variables
Only the general variables are supported (see General Variables for All Requests).
The following tables show the permissions and API operations covered by each verb. The level
of access is cumulative as you go from inspect > read > use > manage. A plus sign (+) in a
table cell indicates incremental access compared to the cell directly above it, whereas "no
extra" indicates no incremental access.
For example, the read and use verbs for the db-systems resource-type cover no extra
permissions or API operations compared to the inspect verb. However, the manage verb
includes two more permissions and partially covers two more API operations.
db-systems
INSPECT
GetDbSystem
ListDbSystemPatches
ListDbSystemPatchHistoryEntries
GetDbSystemPatch
GetDbSystemPatchHistoryEntry
READ
USE
inspect db-backups)
MANAGE
db-nodes
INSPECT
DB_NODE_QUERY
READ
USE
MANAGE
DB_NODE_POWER_ACTIONS
db-homes
INSPECT
GetDBHome
ListDbHomePatches
ListDbHomePatchHistoryEntries
GetDbHomePatch
GetDbHomePatchHistoryEntry
READ
USE
inspect backups)
MANAGE
backups
databases.
databases
INSPECT
GetDatabase
ListDataGuardAssociations
GetDataGuardAssociation
READ
no extra no extra
DATABASE_CONTENT_READ
USE
MANAGE
subnets)
backups
INSPECT
db-databases)
READ
DB_BACKUP_CONTENT_READ databases)
USE
MANAGE
DB_BACKUP_CREATE
DB_BACKUP_DELETE
The following tables list the API operations for DB systems in a logical order, grouped by
resource type.
ListDbSystems DB_SYSTEM_INSPECT
GetDbSystem DB_SYSTEM_INSPECT
ListDbSystemPatches DB_SYSTEM_INSPECT
ListDbSystemPatchHistoryEntries DB_SYSTEM_INSPECT
GetDbSystemPatch DB_SYSTEM_INSPECT
GetDbSystemPatchHistoryEntry DB_SYSTEM_INSPECT
GetDbNode DB_NODE_INSPECT
DbNodeAction DB_NODE_POWER_ACTIONS
ListDbHomes DB_HOME_INSPECT
GetDbHome DB_HOME_INSPECT
ListDbHomePatches DB_HOME_INSPECT
ListDbHomePatchHistoryEntries DB_HOME_INSPECT
GetDbHomePatch DB_HOME_INSPECT
GetDbHomePatchHistoryEntry DB_HOME_INSPECT
UpdateDbHome DB_HOME_UPDATE
ListDatabases DATABASE_INSPECT
GetDatabase DATABASE_INSPECT
UpdateDatabase DATABASE_UPDATE
GetDataGuardAssociation DATABASE_INSPECT
ListDataGuardAssociations DATABASE_INSPECT
SwitchoverDataGuardAssociation DATABASE_UPDATE
FailoverDataGuardAssociation DATABASE_UPDATE
ReinstateDataGuardAssociation DATABASE_UPDATE
GetBackup DB_BACKUP_INSPECT
ListBackups DB_BACKUP_INSPECT
Aggregate Resource-Type
dns
Individual Resource-Types
dns-zones
dns-records
dns-steering-policies
dns-steering-policy-attachments
dns-tsig-keys
COMMENTS
A policy that uses <verb> dns is equivalent to writing one with a separate <verb>
<individual resource-type> statement for each of the individual resource-types.
See the table in Details for Verb + Resource-Type Combinations for a detailed breakout of the
API operations covered by each verb, for each individual resource-type included in dns.
Supported Variables
The DNS service supports all the general variables (see General Variables for All Requests),
plus the ones listed here.
target.dns- Entity Use this variable to control access to specific DNS zones
zone.id (OCID) by OCID.
target.dns- String Use this variable to control access to specific DNS zones
zone.name by name.
target.dns- String The most significant DNS label for the target zone.
zone.apex-label Example: If the target zone's name is
"service.example.com", the value of this variable would
be “service”.
target.dns- String The domain name of the target zone's parent zone.
zone.parent-
domain
target.dns- Entity Use this variable to control access to specific DNS zones
zone.id (OCID) by OCID.
target.dns- String Use this variable to control access to specific DNS zones
zone.name by name.
Note
The following tables show the permissions and API operations covered by each verb. The level
of access is cumulative as you go from inspect > read > use > manage. A plus sign (+) in a
table cell indicates incremental access compared to the cell directly above it, whereas "no
extra" indicates no incremental access.
For example, the manage verb for the dns-records resource-type covers no extra
permissions or API operations compared to the use verb.
dns-zones
INSPECT
READ
DNS_ZONE_READ
USE
DNS_ZONE_UPDATE PatchZoneRecords
CreateSteeringPolicyAttachment
DeleteSteeringPolicyAttachment
MANAGE
DNS_ZONE_CREATE DeleteZone
DNS_ZONE_DELETE ChangeZoneCompartment
DNS_ZONE_MOVE
dns-records
INSPECT
READ
DNS_RECORD_READ GetRRSet
USE
DeleteRRSet UpdateSteeringPolicyAttachment
PatchRRSet
UpdateRRSet
MANAGE
DNS_RECORD_CREATE
DNS_RECORD_DELETE
dns-steering-policies
INSPECT
READ
DeleteSteeringPolicyAttachment
USE
DNS_POLICY_STEERING_UPDATE
MANAGE
DNS_STEERING_POLICY_CREATE DeleteSteeringPolicy
DNS_STEERING_POLICY_DELETE ChangeSteeringPolicyCompartment
DNS_STEERING_POLICY_MOVE
dns-steering-policy-attachments
INSPECT
READ
DNS_STEERING_ATTACHMENT_READ
dns-tsig-keys
INSPECT
READ
DNS_TSIG_KEY_READ
USE
DNS_TSIG_KEY_UPDATE
MANAGE
DNS_TSIG_KEY_CREATE DeleteTsigKey
DNS_TSIG_KEY_DELETE ChangeTsigKeyCompartment
DNS_TSIG_KEY_MOVE
The following table lists the API operations in a logical order, grouped by resource type.
ListZones DNS_ZONE_INSPECT
CreateZone DNS_ZONE_CREATE
CreateChildZone DNS_ZONE_CREATE
InspectParentZone DNS_ZONE_INSPECT
DeleteZone DNS_ZONE_DELETE
GetZone DNS_ZONE_READ
UpdateZone DNS_ZONE_UPDATE
ChangeZoneCompartment DNS_ZONE_MOVE
GetDomainRecords DNS_RECORD_READ
PatchDomainRecords DNS_RECORD_UPDATE
UpdateDomainRecords DNS_RECORD_UPDATE
DeleteRRSet DNS_RECORD_UPDATE
GetRRSet DNS_RECORD_READ
PatchRRSet DNS_RECORD_UPDATE
UpdateRRSet DNS_RECORD_UPDATE
ListSteeringPolicies DNS_STEERING_
POLICY_INSPECT
CreateSteeringPolicy DNS_STEERING_
POLICY_CREATE
GetSteeringPolicy DNS_STEERING_
POLICY_READ
UpdateSteeringPolicy DNS_STEERING_
POLICY_UPDATE
DeleteSteeringPolicy DNS_STEERING_
POLICY_DELETE
ChangeSteeringPolicyCompartment DNS_STEERING_
POLICY_MOVE
ListSteeringPolicyAttachments DNS_STEERING_
ATTACHMENT_INSPECT
GetSteeringPolicyAttachment DNS_STEERING_
ATTACHMENT_READ
ListTsigKeys DNS_TSIG_KEY_
INSPECT
CreateTsigKey DNS_TSIG_KEY_CREATE
GetTsigKey DNS_TSIG_KEY_READ
UpdateTsigKey DNS_TSIG_KEY_UPDATE
DeleteTsigKey DNS_TSIG_KEY_DELETE
ChangeTsigKeyCompartment DNS_TSIG_KEY_MOVE
Resource-Types
approved-senders
suppressions
Supported Variables
The Email Service supports all the general variables (see General Variables for All Requests),
plus the ones listed here.
The following tables show the permissions and API operations covered by each verb. The level
of access is cumulative as you go from inspect > read > use > manage. A plus sign (+) in a
table cell indicates incremental access compared to the cell directly above it, whereas "no
extra" indicates no incremental access.
For example, the use verb for the suppressions resource-type covers no extra permissions
or API operations compared to the read verb.
approved-senders
INSPECT
READ
APPROVED_SENDER_READ
USE
APPROVED_SENDER_USE
MANAGE
APPROVED_SENDER_CREATE DeleteSender
APPROVED_SENDER_DELETE UpdateSender
APPROVED_SENDER_UPDATE MoveSender
APPROVED_SENDER_MOVE
suppressions
INSPECT
READ
SUPPRESSION_READ
USE
No extra None
None
MANAGE
SUPPRESSION_CREATE DeleteSuppression
SUPPRESSION_DELETE
The following table lists the API operations in a logical order, grouped by resource type.
ListSenders APPROVED_SENDER_INSPECT
GetSender APPROVED_SENDER_READ
CreateSender APPROVED_SENDER_CREATE
DeleteSender APPROVED_SENDER_DELETE
MoveSender APPROVED_SENDER_MOVE
SmtpSend APPROVED_SENDER_USE
ListSuppression SUPPRESSION_INSPECT
GetSuppression SUPPRESSION_READ
CreateSuppression SUPPRESSION_CREATE
DeleteSuppression SUPPRESSION_DELETE
Resource-Types
cloudevents-rules
Supported Variables
Only the general variables are supported (see General Variables for All Requests).
The following tables show the permissions and API operations covered by each verb. The level
of access is cumulative as you go from inspect > read > use > manage. A plus sign (+) in a
table cell indicates incremental access compared to the cell directly above it, whereas "no
extra" indicates no incremental access.
For example, the read verb for cloudevents-rules includes the same permissions and API
operations as the inspect verb, plus the EVENTRULE_READ permissions and the
corresponding API operation GetEventRule. The use verb adds no extra permissions or API
operations compared to read. However, manage adds more permissions and operations
compared to use.
CLOUDEVENTS-RULES
INSPECT
READ
EVENTRULE_READ GetRule
USE
MANAGE
EVENTRULE_CREATE CreateRule
EVENTRULE_DELETE DeleteRule
EVENTRULE_MODIFY UpdateRule
ChangeRuleCompartment
The following table lists the API operations in a logical order, grouped by resource type.
ListRules EVENTRULE_LIST
CreateRule EVENTRULE_CREATE
GetRule EVENTRULE_READ
DeleteRule EVENTRULE_DELETE
UpdateRule EVENTRULE_MODIFY
ChangeRuleCompartment EVENTRULE_MODIFY
Aggregate Resource-Type
l file-family
Individual Resource-Types
l file-systems
l mount-targets
l export-sets
COMMENTS
A policy that uses <verb> file-family is equivalent to writing one with a separate <verb>
<individual resource-type> statement for each of the individual resource-types.
See the table in Details for Verb + Resource-Type Combinations for a detailed breakout of the
API operations covered by each verb, for each individual resource-type included in file-
family.
Supported Variables
Only the general variables are supported (see General Variables for All Requests).
The following tables show the permissions and API operations covered by each verb. The level
of access is cumulative as you go from inspect > read > use > manage. A plus sign (+) in a
table cell indicates incremental access compared to the cell directly above it, whereas "no
extra" indicates no incremental access.
For example, the read verb for the file-systems resource-type includes the same
permissions and API operations as the inspect verb, plus the FILE_SYSTEM_READ permission
and a number of API operations (e.g., GetFileSystem, ListMountTargets, etc.). The use
verb covers still another permission and set of API operations compared to read. Lastly,
manage covers two more permissions and operations compared to use.
export-sets
INSPECT
READ
EXPORT_SET_READ GetExport
GetExportSet
ListExports
USE
MANAGE
EXPORT_SET_DELETE DeleteExportSet
file-systems
INSPECT
READ
FILE_SYSTEM_READ GetFileSystem
GetSnapshot
ListSnapshots
USE
MANAGE
FILE_SYSTEM_DELETE DeleteFileSystem
read keys (for the service principal). For
FILE_SYSTEM_CREATE_SNAPSHOT CreateSnapshot
more information, see Details for the Vault
FILE_SYSTEM_DELETE_SNAPSHOT DeleteSnapshot
Service.
mount-targets
INSPECT
READ
MOUNT_TARGET_READ GetMountTarget
USE
MANAGE
MOUNT_TARGET_CREATE CreateMountTarget,
MOUNT_TARGET_UPDATE DeleteMountTarget
The following table lists the API operations in a logical order, grouped by resource type.
Tip
ListExports EXPORT_SET_READ
GetExport EXPORT_SET_READ
ListExportSets EXPORT_SET_INSPECT
CreateExportSet EXPORT_SET_CREATE
GetExportSet EXPORT_SET_READ
UpdateExportSet EXPORT_SET_UPDATE
DeleteExportSet EXPORT_SET_DELETE
ListFileSystems FILE_SYSTEM_INSPECT
CreateFileSystem FILE_SYSTEM_CREATE
GetFileSystem FILE_SYSTEM_READ
UpdateFileSystem FILE_SYSTEM_UPDATE
DeleteFileSystem FILE_SYSTEM_DELETE
ListMountTargets MOUNT_TARGET_INSPECT
CreateMountTarget MOUNT_TARGET_CREATE +
VNIC_CREATE(vnicCompartment) +
SUBNET_ATTACH(subnetCompartment) +
VNIC_ATTACH(vnicCompartment) +
PRIVATE _IP_CREATE(subnetCompartment) +
PRIVATE_IP_ASSIGN(subnetCompartment) +
VNIC_ASSIGN(subnetCompartment)
GetMountTarget MOUNT_TARGET_READ
UpdateMountTarget MOUNT_TARGET_UPDATE
DeleteMountTarget MOUNT_TARGET_DELETE +
VNIC_DELETE(vnicCompartment) +
SUBNET_DETACH(subnetCompartment) +
VNIC_DETACH(vnicCompartment) +
PRIVATE_IP_DELETE(subnetCompartment) +
PRIVATE_IP_UNASSIGN(subnetCompartment) +
VNIC_UNASSIGN(vnicCompartment)
ListSnapshots FILE_SYSTEM_READ
CreateSnapshot FILE_SYSTEM_CREATE_SNAPSHOT
GetSnapshot FILE_SYSTEM_READ
DeleteSnapshot FILE_SYSTEM_DELETE_SNAPSHOT
Resource-Types
l functions-family
l fn-app
l fn-function
l fn-invocation
COMMENTS
A policy that uses <verb> functions-family is equivalent to writing one with a separate
<verb> <individual resource-type> statement for each of the individual resource-types.
See the table in Details for Verb + Resource-Type Combinations for a detailed breakout of the
API operations covered by each verb, for each individual resource-type included in
functions-family.
Supported Variables
Oracle Functions supports all the general variables (see General Variables for All Requests).
The following tables show the permissions and API operations covered by each verb. The level
of access is cumulative as you go from inspect > read > use > manage. A plus sign (+) in a
table cell indicates incremental access compared to the cell directly above it, whereas "no
extra" indicates no incremental access.
For example, the read verb for the fn-app resource-type includes the same permissions and
API operations as the inspect verb, plus the FN_APP_READ permission and the GetApp API
operation. In the case of the fn-app resource-type, the use verb covers no additional
permissions or API operations compared to read. Lastly, manage covers more permissions
and operations compared to use.
fn-app
INSPECT
READ
FN_APP_READ GetApp
USE
MANAGE
FN_APP_CREATE CreateApp
FN_APP_DELETE DeleteApp
FN_APP_UPDATE UpdateApp
fn-function
INSPECT
READ
FN_FUNCTION_READ GetFunction
USE
MANAGE
FN_FUNCTION_CREATE CreateFunction
FN_FUNCTION_DELETE DeleteFunction
FN_FUNCTION_UPDATE UpdateFunction
fn-invocation
INSPECT
READ
USE
MANAGE
The following table lists the API operations in a logical order, grouped by resource type. For
information about permissions, see Permissions.
CreateApp FN_APP_CREATE
DeleteApp FN_APP_DELETE
ListApp FN_APP_LIST
GetApp FN_APP_READ
UpdateApp FN_APP_UPDATE
CreateFunction FN_FUNCTION_CREATE
DeleteFunction FN_FUNCTION_DELETE
ListFunctions FN_FUNCTION_LIST
GetFunction FN_FUNCTION_READ
UpdateFunction FN_FUNCTION_UPDATE
InvokeFunction FN_INVOCATION
Resource-Types
health-check-monitor
health-check-results
on-demand-probe
vantage-points
health-check-family
Supported Variables
The Health Checks Service supports all the general variables (see General Variables for All
Requests), plus the ones listed here. Values in the list can be any valid test type. For example,
HTTP, HTTPS, ICMP, etc.
target.health- String
check-monitor.test-
type
target.on-demand- String
probe.test-type
target.health- String
check-results.test-
type
The following tables show the permissions and API operations covered by each verb. The level
of access is cumulative as you go from inspect > read > use > manage. A plus sign (+) in a
table cell indicates incremental access compared to the cell directly above it, whereas "no
extra" indicates no incremental access.
For example, the use verb for the health-check-monitor resource-type covers no extra
permissions or API operations compared to the read verb.
health-check-monitor
INSPECT
READ
HEALTH_CHECK_MONITOR_READ
USE
MANAGE
HEALTH_CHECK_MONITOR_MANAGE UpdateOHCMonitor
DeleteOHCMonitor
MoveOHCMonitor
health-check-results
INSPECT
READ
ListOHCProbeResultsForTarget
USE
MANAGE
vantage-points
INSPECT
READ
USE
MANAGE
on-demand-probe
INSPECT
READ
USE
MANAGE
ON_DEMAND_PROBE_MANAGE
The following table lists the API operations in a logical order, grouped by resource type.
ListOHCMonitors HEALTH_CHECK_MONITOR_INSPECT
CreateOHCMonitor HEALTH_CHECK_MONITOR_MANAGE
GetOHCMonitor HEALTH_CHECK_MONITOR_READ
UpdateOHCMonitor HEALTH_CHECK_MONITOR_MANAGE
DeleteOHCMonitor HEALTH_CHECK_MONITOR_MANAGE
ListOHCProbeResults HEALTH_CHECK_RESULTS_READ
ListOHCProbeResultsForTarget HEALTH_CHECK_RESULTS_READ
ListVantagePoints VANTAGE_POINTS_INSPECT
CreateOnDemandOHCProbe ON_DEMAND_PROBE_MANAGE
MoveOHCMonitor HEALTH_CHECK_MONITOR_MOVE
Resource-Types
authentication-policies
compartments
credentials
dynamic-groups
groups
identity-providers
network-sources
policies
tag-defaults
tag-namespaces
tenancies
users
workrequest
Supported Variables
IAM supports all the general variables (see General Variables for All Requests), plus
additional ones listed here:
target String
.user.name
target String
.group.name
target String
.
policy.name
target Boolean Whether the policy being acted upon uses "Keep
. policy current" as its version date (i.e., either
policy null or an empty string for the versionDate
.autoupdate parameter in CreatePolicy and UpdatePolicy).
target. String
compartment
.name
target.tag- String
namespace
.name
The following tables show the permissions and API operations covered by each verb. The level
of access is cumulative as you go from inspect > read > use > manage. A plus sign (+) in a
table cell indicates incremental access compared to the cell directly above it, whereas "no
extra" indicates no incremental access.
For example, the read verb for compartments covers no extra permissions or API operations
compared to the inspect verb. The use verb includes the same ones as the read verb, plus
authentication-policies
INSPECT
READ
USE
MANAGE
AUTHENTICATION_POLICY_UPDATE UpdateAuthenticationPolicy
compartments
To move a compartment (that is, use the MoveCompartment operation) you must belong to a
group that has manage all-resources permissions on the lowest shared parent compartment
of the current compartment and the destination compartment.
INSPECT
GetCompartment
ListAvailabilityDomains
ListFaultDomains
READ
USE
COMPARTMENT_UPDATE UpdateCompartment
GetWorkRequest
MANAGE
COMPARTMENT_CREATE CreateCompartment
COMPARTMENT_DELETE DeleteCompartment
COMPARTMENT_RECOVER RecoverCompartment
credentials
The credentials resource type refers to only the SMTP credentials. Permissions to work with
other credentials that can be added to a user (such as auth tokens, API keys, and customer
secret keys) are included with users resource permissions.
INSPECT
READ
no extra