Mount API

Table of Contents

Use the Mount API to mount a drive, such as S3 or NFS, or mount a database, like MySQL or Oracle, that your application can then interact with.

See Instabase API authorization and response conventions for authorization, success response, and error response convention details.

For the Mount API, api-root defines where to route API requests for your Instabase instance:

import json, requests
api_root = "https://instabase.com/api/v1"

Mount drive

Use this API to mount a drive.

Request

import json, requests

headers = {'Authorization': 'Bearer {0}'.format(token)}
args = {
  'action':'mount',
  'mount_point_name': '...', 
  'mount_details': { 
    ...
  }
}
data = json.dumps(args)
resp = requests.post(api_root + '/drives/<repo_owner>/<repo_name>/fs', 
                     headers=headers, data=data).json()

The body of the request must be a JSON object with the following fields:

action: String describing the action to be taken. Valid values are: [‘mount’].
mount_point_name: The name of the mounted drive
mount_details: Details of drive to mount.

Mount details will vary by the type of drive being mounted.

Amazon S3 bucket mount details

For an S3 bucket, provide mount details in the following structure:

'mount_details': { 
  'client_type': 'S3',
  'prefix': '<Path to mount (ex: files/data)>' ,
  's3_server_url': '<S3 Server URL>',
  's3_server_port': '<S3 Server Port>', 
  's3_server_is_secure': 'True' | 'False',
  's3_server_validate_certs': 'True' | 'False',
  'use_aws_access_creds': True | False,
  'aws_access_key_id': '<AWS access key>', # Optional, use if 'use_aws_access_creds' is set to True
  'aws_secret_access_key': '<AWS secret access key>', # Optional, use if 'use_aws_access_creds' is set to True
  'bucket_name': '<AWS S3 Bucket Name>', 
  'aws_region': 'AWS Region (ex: us-east-1)', 
  'encryption_type': 'none' | 'kms_encryption', 
  's3_sse_encryption_type': 'none' | 'aws_sse_s3' | 'aws_sse_kms', 
  's3_sse_kms_key_id': '<S3 SSE KMS key ID>', # Optional, use if 's3_sse_encryption_type' is set to 'aws_sse_kms'
  's3_use_virtual_style_url': True | False, 
  'use_hcp_s3_storage': True | False, 
  'mount_permissions': '{"access_level":"writer"}' | '{"access_level":"reader"}' 
}

Note

If s3_sse_encryption_type is set to aws_sse_kms, define the Amazon resource name (ARN) for the KMS key in s3_sse_kms_key_id. For example, 'arn:aws:kms:us-west-2:123456789012:key/abcd1234-5678-90ab-cdef-EXAMPLE11111'. See the AWS Finding the key ID and key ARN documentation for additional information.

Local drive mount details

To mount a local drive, you first must set up a local drive. For local drives, provide mount details in the following structure:

'mount_details': { 
  'client_type': 'LocalFS', 
  'local_mount_dir': '<Path to local mount directory on the file-service pod>', 
  'encryption_type': 'none' | 'kms_encryption', 
  'mount_permissions': '{"access_level":"reader"}' | '{"access_level":"writer"}'
}

Azure Blob Storage mount details

For Azure Blob Storage drives, they can be mounted with a connection string or a service principal as the authentication type.

If mounting an Azure Blob Storage container with a connection string, provide mount details in the following structure:

'mount_details': { 
  'client_type': 'AzureBlob',
  'az_blob_store_auth_type': 'connection_string', # Defaults to 'connection_string' if left empty
  'azure_container_name': '<Azure Blob Storage container name>', 
  'azure_connect_str': '<Azure storage account connection string>' 
  'mount_permissions': '{"access_level":"reader"}' | '{"access_level":"writer"}'
}

See the following sample connection string structure for an Azure storage account with default configurations. Connection strings can embed a different subset of fields:

'DefaultEndpointsProtocol=[http|https];AccountName=myAccountName;AccountKey=myAccountKey;EndpointSuffix=[core.windows.net]'

If mounting an Azure Blob Storage container with a service principal, provide mount details in the following structure:

'mount_details': { 
  'client_type': 'AzureBlob',
  'az_blob_store_auth_type': 'service_principal', # Defaults to 'connection_string' if left empty
  'azure_container_name': '<Azure Blob Storage container name>', 
  'az_blob_store_client_id': '<Azure storage account client ID>',
  'az_blob_store_tenant_id': '<Azure storage account tenant ID>',
  'az_blob_store_client_secret': '<Azure storage account client secret>',
  'az_blob_store_service_url': '<Azure storage account service URL>',
  'mount_permissions': '{"access_level":"reader"}' | '{"access_level":"writer"}'
}

Google Cloud Storage mount details

For Google Cloud Storage drives, required fields include bucket_name and gcs_service_account_creds. The bucket_name is the name of the Google Cloud Storage bucket, and gcs_service_account_creds is a JSON object that contains the service account credentials.

Provide mount details in the following structure:

'mount_details': { 
  'client_type': 'GoogleCloudStorage', 
  'bucket_name': '<Google Cloud Storage Bucket Name>', 
  'gcs_service_account_creds': '<Google Cloud Storage Service Account Credentials>', 
  'encryption_type': 'none', 
  'mount_permissions': '{"access_level":"reader"}' | '{"access_level":"writer"}'
}

Response

If the Drive was successfully mounted:

HTTP STATUS CODE 200

{
  "status": "OK"
}

Update drive credentials

Use this API to update drive credentials.

Request

import json, requests

headers = {'Authorization': 'Bearer {0}'.format(token)}
args = {
  {
    "mount_point_name": "...",
    "mount_details": { 
      ...
    }
  }
}
data = json.dumps(args)
resp = requests.put(api_root + '/drives/<repo_owner>/<repo_name>/fs', headers=headers, data=data).json()

The body of the request is a JSON object with the following fields:

mount_point_name: The name of the mounted drive.
mount_details: A JSON object containing new credentials for the mounted drive.

Note

This endpoint can’t be used to update non-credential fields in the mount_details object. See the following examples for supported fields.

For an S3 bucket, you can update the following drive credentials fields:

'mount_details': {
  'aws_access_key_id': '<AWS access key>', # If 'use_aws_access_creds' is set to True
  'aws_secret_access_key': '<AWS secret access key>', # If 'use_aws_access_creds' is set to True 
}

For Azure Blob Storage drives mounted with a connection string, you can update the following drive credentials fields:

'mount_details': {
  'azure_connect_str': '<Azure storage account connection string>',
}

For Azure Blob Storage drives mounted with a service principal, you can update the following drive credentials fields:

'mount_details': {
  'az_blob_store_client_id': '<Azure storage account client ID>',
  'az_blob_store_tenant_id': '<Azure storage account tenant ID>',
  'az_blob_store_client_secret': '<Azure storage account client secret>',
  'az_blob_store_service_url': '<Azure storage account service URL>',
}

For Google Cloud Storage drives, you can update the following drive credentials fields:

'mount_details': {
  'gcs_service_account_creds': '<GCS service account credentials in JSON>',
}

Response

If the drive credentials were successfully updated:

HTTP STATUS CODE 200

{
  "status": "OK"
}

Unmount drive

Use this API to unmount a drive.

Request

import json, requests

headers = {'Authorization': 'Bearer {0}'.format(token)}
args = {
  'name': '<Mount point name>' 
}
data = json.dumps(args)
resp = requests.delete(api_root + '/drives/<repo_owner>/<repo_name>/fs', headers=headers, data=data).json()

Response

If the credentials to the drive was successfully unmounted:

HTTP STATUS CODE 200

{
  "status": "OK"
}

Edit mounted drive point

Use this API to edit a drive mount point name.

Request

import json, requests

headers = {'Authorization': 'Bearer {0}'.format(token)}
args = {
  'old_name': '<Old mount point name>', 
  'new_name': '<New mount point name>'
}
data = json.dumps(args)
resp = requests.patch(api_root + '/drives/<repo_owner>/<repo_name>/fs', headers=headers, data=data).json()

Response

If the drive mount point name was successfully updated:

HTTP STATUS CODE 200

{
  "status": "OK"
}

Mount database

Use this API to mount a database.

Request

import json, requests

headers = {'Authorization': 'Bearer {0}'.format(token)}
args = {
  'action':'mount',
  'user_form': {...}
}
data = json.dumps(args)
resp = requests.post(api_root + '/databases/<repo_owner>/<repo_name>/databases', headers=headers, data=data).json()

If mounting a MySQL, Postgres, Microsoft SqlServer, or Amazon Redshift database, user_form looks like:

'user_form': { 
  'service' (required): 'mysql' | 'postgres' | 'microsoft-sql-server' | 'amazon-redshift',
  'username' (required): '<db username>', 
  'password' (required): '<db password>', 
  'databaseName': '<db name>', 
  'useTnsadmin': False,
  'host' (required): '<db host>', 
  'port': '<db port>', 
  'mountAccessLevel': 'reader' | 'writer', 
  'mountName': '<name for mounted db>'
}

If mounting an Oracle database, useTnsadmin can be set to True, in which case host and port don’t need to be provided. When mounting an Oracle database, user_form looks like:

Note

Required parameters are indicated with a (required) tag.

'user_form': { 
  'service' (required): 'oracle',
  'username' (required): '<db username>', 
  'password' (required): '<db password>', 
  'databaseName': '<db name>', 
  'oracle_service_name': '<service name>',
  'useTnsadmin': False | True, # can set to True only if using service 'oracle'
  'host' (required): '<db host>', 
  'port': '<db port>', 
  'mountAccessLevel': 'reader' | 'writer', 
  'mountName': '<name for mounted db>'
}

Response

If database was successfully mounted:

HTTP STATUS CODE 200

{
  "status": "OK"
}

Unmount database

Use this API to unmount a database.

Request

import json, requests

headers = {'Authorization': 'Bearer {0}'.format(token)}
args = {
  'name': '<Mount point name>' 
}
data = json.dumps(args)
resp = requests.delete(api_root + '/databases/<repo_owner>/<repo_name>/databases', headers=headers, data=data).json()

Response

If the database was successfully unmounted:

HTTP STATUS CODE 200

{
  "status": "OK"
}

Edit mounted database point

Use this API to edit a database mount point name.

Request

import json, requests

headers = {'Authorization': 'Bearer {0}'.format(token)}
args = {
  'old_name': '<Old mount point name>', 
  'new_name': '<New mount point name>'
}
data = json.dumps(args)
resp = requests.patch(api_root + '/databases/<repo_owner>/<repo_name>/databases', headers=headers, data=data).json()

Response

If the database mount point name was successfully updated:

HTTP STATUS CODE 200

{
  "status": "OK"
}