Using a Runtime Configuration

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.

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.

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.