Getting Connected

Configuring Your Connection

There are two IAM policy validation options in ocifs. The first option is using an identity policy, which is a configuration file. This is the most commonly used policy, and is the default in this documentation.

from ocifs import OCIFileSystem

fs = OCIFileSystem(config="~/.oci/config", profile="DEFAULT")

Using Pandas and Dask are just as easy:

import pandas as pd

pd.read_csv("oci://bucket@namespace/path/file.csv",
            storage_options={"config": "~/.oci/config", "profile": "DEFAULT"})

from dask import dataframe as dd

dd.read_csv("oci://bucket@namespace/path/file.csv",
            storage_options={"config": "~/.oci/config", "profile": "DEFAULT"})

Using Environment Variables

Users can provide default authentication configuration details as enviornment variables. The following environment variables are inspected:

• OCIFS_IAM_TYPE: which can be any of: [“api_key”, “resource_principal”, “instance_principal”, “unknown_signer”]

• OCIFS_CONFIG_LOCATION: (optional) will be referenced in the case of “api_key”, but defaults to the default config location provided by the oci sdk

• OCIFS_CONFIG_PROFILE: (optional) will be referenced in the case of “api_key”, but defaults to the default config profile provided by the oci sdk

import os

os.environ['OCIFS_IAM_TYPE'] = "api_key"
fs = OCIFileSystem()

Note, the order of precedence for authentication is: signer arg, config arg, environment variables, then ocifs will attempt to set up Resource Principal, as exemplified below.

Resource Principal

The second policy option is using a resource principal. This policy only works if you’re operating within a valid OCI resource, such as an OCI Data Science notebook session. With this option, your resource token path is set by global OCI signing variables.

fs = OCIFileSystem()

And with pandas or dask:

pd.read_csv("oci://bucket@namespace/path/file.csv")

dd.read_csv("oci://bucket@namespace/path/file.csv")

Connecting Using a Signer

Any signer can be passed in using the signer argument.

resource_principal_signer = oci.auth.signers.get_resource_principals_signer()
fs_rp = OCIFileSystem(signer=resource_principal_signer)

instance_principal_signer = oci.auth.signers.InstancePrincipalsSecurityTokenSigner()
fs_ip = OCIFileSystem(signer=instance_principal_signer)

And with pandas or dask:

pd.read_csv("oci://bucket@namespace/path/file.csv",
            storage_options={"signer": resource_principal_signer})

dd.read_csv("oci://bucket@namespace/path/file.csv",
            storage_options={"signer": instance_principal_signer})

Connecting to a Different Region

Each filesystem instance has a home region and won’t operate outside of that region. The home region defaults to the region of the IAM policy. With a configuration policy, it is region. With a resource principal, the region is derived from the OCI_REGION_METADATA environment variable.

The OCIFileSystem delegates this region set up to the Object Storage Client init method in the OCI Python SDK. The region argument accepts any valid region identifier and constructs the corresponding service endpoint for the Object Storage Client. The following cell is an example of connecting to the sydney region.

fs_sydney = OCIFileSystem(config="~/.oci/config", region="ap-sydney-1")

Using Pandas or Dask:

df.to_csv("oci://bucket@namespace/path/file.csv",
          storage_options = {"config": "~/.oci/config", "region": "ap-sydney-1"})

ddf.to_csv("oci://bucket@namespace/path/file.csv",
           storage_options = {"config": "~/.oci/config", "region": "ap-sydney-1"})

Note: You must ensure that you have valid cross-region permissions before attempting to instantiate a file system in a non-home region, see the list of valid OCI Region Identifiers.