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.
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 |
---|---|---|
|
OCID of the tenancy the notebook belongs to. |
Automatically populated by Data Science. |
|
The OCID of the project associated with the current notebook session. |
Automatically populated by Data Science. |
|
OCID of the compartment of the project the notebook is associated with. |
Automatically populated by Data Science. |
|
User OCID. |
Automatically populated by Data Science. |
|
The OCID of the current notebook session. |
Automatically populated by Data Science. |
|
The compartment OCID of the current notebook session. |
Automatically populated by Data Science. |
|
Path to the OCI resource principal token. |
Automatically populated by Data Science. |
|
Id of the OCI resource principal token. |
Automatically populated by Data Science. |
|
Notebook session lifecycle script URL to run when creating. |
User specified. |
|
Notebook session lifecycle script URL to run when activating. |
User specified. |
|
Notebook session lifecycle script URL to run when deactivating. |
User specified. |
|
Notebook session lifecycle script URL to run when deleting. |
User specified. |
|
Object Storage namespace for notebook lifecycle script output logs. |
User specified. |
|
Object Storage bucket for notebook lifecycle script output logs. |
User specified. |
|
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
.
- Find the clones of Git repositories in a notebook session's
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.