Using a Runtime Configuration

When you create a notebook session, you can add custom environment variable keys and Git repository URLs to be used in notebook sessions.

Note

Don't name environment variable keys with the service managed environment names in the following table, because the keys expect certain values or the Data Science service automatically returns the value.

Service Managed Environment Variables

Variable Key Name

Description

Specified By

TENANCY_OCID

OCID of the tenancy the notebook belongs to.

Automatically populated by Data Science.

PROJECT_OCID

The OCID of the project associated with the current notebook session.

Automatically populated by Data Science.

PROJECT_COMPARTMENT_OCID

OCID of the compartment of the project the notebook is associated with.

Automatically populated by Data Science.

USER_OCID

User OCID.

Automatically populated by Data Science.

NB_SESSION_OCID

The OCID of the current notebook session.

Automatically populated by Data Science.

NB_SESSION_COMPARTMENT_OCID

The compartment OCID of the current notebook session.

Automatically populated by Data Science.

OCI_RESOURCE_PRINCIPAL_RPT_PATH

Path to the OCI resource principal token.

Automatically populated by Data Science.

OCI_RESOURCE_PRINCIPAL_RPT_ID

Id of the OCI resource principal token.

Automatically populated by Data Science.

NB_ONCREATE_SCRIPT_URL

Notebook session lifecycle script URL to run when creating.

User specified.

NB_ONACTIVATE_SCRIPT_URL

Notebook session lifecycle script URL to run when activating.

User specified.

NB_ONDEACTIVATE_SCRIPT_URL

Notebook session lifecycle script URL to run when deactivating.

User specified.

NB_ONDELETE_SCRIPT_URL

Notebook session lifecycle script URL to run when deleting.

User specified.

NB_SCRIPT_OUTPUT_LOG_NAMESPACE

Object Storage namespace for notebook lifecycle script output logs.

User specified.

NB_SCRIPT_OUTPUT_LOG_BUCKET

Object Storage bucket for notebook lifecycle script output logs.

User specified.

SECURE_DATA_SESSION

Disable file download from JupyterLab client and JupyterLab download API, set to True to disable download functionality.

User specified.

Custom Environment Variable Keys

In addition to system provided variables, you can add custom environment variable keys to notebook sessions. When you create a notebook session, add custom variables as key value pairs in the Runtime configuration section.

Key Value Pair Constraints
  • Keys and values are case-sensitive.

  • Keys must start with a letter or underscore, and only contain alphanumerics and underscores.

  • Key length is a minimum of 2 and maximum of 32 characters.

  • Value length is a minimum of 1 and maximum of 256 characters.

  • Keys can't start with the service reserved namespace of oci_internal_.

  • Keys can't be service managed variables.

For an existing notebook session, deactivate the notebook sessions. Then when you activate the notebook, add the key value pairs in the Runtime configuration section.

Using Custom Environment Variable Keys to Manage Notebook Session Lifecycle Scripts

You can use the notebook session lifecycle scripts to run a custom script at different notebook session lifecycle states as follows:

  • Create

  • Activate

  • Deactivate

  • Delete

To run a notebook lifecycle script, pass in a service managed key in the Runtime Configuration section that indicates the lifecycle state to run the script in. In the corresponding value field, specify the OCI Object Storage file URI where the lifecycle script has been uploaded.

The notebook state doesn't change until the script has completed for delete and deactivate lifecycle states. Create and activate lifecycle scripts run in parallel with the notebook session so no start delays occur.

We've provided several example notebook lifecycle scripts that can be changed to suit various use cases.

A notebook session dynamic group and policy to use a resource principal must be created to use notebook lifecycle scripts. Read permissions must be granted to the notebook dynamic group for the Object Storage bucket containing the lifecycle scripts.

The notebook session lifecycle script environment variable keys are:

NB_ONCREATE_SCRIPT_URL
NB_ONACTIVATE_SCRIPT_URL
NB_ONDEACTIVATE_SCRIPT_URL
NB_ONDELETE_SCRIPT_URL

These keys must have the following IAM policy added to allow Data Science to read objects from your scripts bucket as in the following example:


allow dynamic-group <notebook_dyn_group> to manage objects in tenancy
 where all {target.bucket.name='<scripts_bucket>',
            any {request.permission='OBJECT_INSPECT',
                 request.permission='OBJECT_READ'}}

For service managed keys corresponding to the preceding notebook lifecycle script keys, the value must be an OCI Object Storage file URI to the uploaded scripts. The URI format is https://objectstorage.region.oraclecloud.com/n/object-storage-namespace/b/bucket/o/filename. You can find the file URI in the Object Details section.

The notebook session lifecycle output script environment variable keys are:

NB_SCRIPT_OUTPUT_LOG_NAMESPACE
NB_SCRIPT_OUTPUT_LOG_BUCKET

These keys must have the following IAM policy added to allow Data Science to create and upload output logs into your logs bucket as in the following example:


allow dynamic-group <notebook_dyn_group> to manage objects in tenancy
 where all {target.bucket.name='<logs_bucket>',
            any {request.permission='OBJECT_CREATE'}}

Creation and activation script logs are available inside the notebooks session in the same path as the runtime configuration in the /opt/log/odsc.log directory.

Log upload occurs with a deactivate or delete notebook session operation, which gives you the option to check the status of the script processing because you lose the notebook session access. This isn't supported for create and activate scripts.

Using a Runtime Configuration to Clone a Git Repository

Git repositories can be cloned inside notebook sessions using a runtime configuration. Only public Git repositories can be cloned with this approach. To clone private Git repositories, use SSH keys for authentication.

You can have the service clone a Git repository in a local directory of a notebook session, and then use Git.

Git Constraints
  • The notebook must have internet access for Git repository to clone.

  • Only public Git repositories are supported.

  • Maximum of three Git repositories URLs are allowed.

  • Maximum length of a URL is 256 characters.

Git-Related Directories in the Notebook Sessions
  • Find the clones of Git repositories in a notebook session's /home/datascience/repos directory.
  • For clone status such as success, failure, or in-progress, go to /opt/log/odsc.log.
  • For verbose logs, go to /var/log/jupyterlab/runtime_config.log.

Access the logs from a terminal in a notebook session.

For existing notebook session, deactivate the notebook sessions. Then when you activate the notebook, add the Git repository URL in the Runtime Configuration section.

If you activate a notebook session with new Git repository URLs, any listed URL in the Runtime Configuration section, including previous URLs from the deactivated notebook sessions are also cloned to the notebook's /home/datascience/repos directory.

To remove a cloned repository from a notebook session, you can delete it from the notebook session's /home/datascience/repos directory.

To replace an old clone from a deactivated notebook with a new one, delete the unwanted Git repository URL listed in the Runtime Configuration section, add the new URL, and then activate the notebook session.