Installer API

Instabase supports installation through API only, letting you integrate the installation process into CI/CD pipelines. This article outlines the required and optional Installer API endpoints used to perform an installation.

Overview of required and optional installation steps

To complete an API-based installation, you must complete the following API calls in this order. Calls are required unless noted as optional.

1. Database configuration

   • (Optional) TLS authentication configuration

2. File system configuration

   • (Amazon S3 storage only, optional) Upload custom Amazon S3 certificate

   • (Google Cloud Storage only) Upload Google Cloud Storage service account credentials

3. Configure platform and Kubernetes cluster-related settings

4. Configure Kubernetes cluster resourcing

5. (Optional) Perform preflight checks to validate configured infrastructure before beginning installation:

   • Observability monitoring service account check

   • Kubernetes role-based access control (RBAC) check

   • File system check

   • Database check

   • Persistent Volume Claim (PVC) check

6. Upload Instabase license

7. Upload base configurations

8. Upload default patches

9. (Optional) Upload network policies

10. (Optional) Create SAML configuration

11. (Optional) Upload SAML IdP metadata XML

12. (Optional) Clear SAML configuration

13. Finalize installation

14. (Optional) Complete SAML configuration

15. Run post-install actions

    • Get the status of post-install actions

Conventions and authentication

Requests

In this document {URL_BASE} defines where to route API requests for your Instabase instance.

During the initial Instabase installation, set api_root to access Deployment Manager directly, either by port-forwarding the Deployment Manager port (9500) or by creating an ingress.

• If using port-forwarding, the URL_BASE value is localhost:9500.

  • For example, to use the Database configuration API, POST to localhost:9500/api/v1/control_plane/installer/db.

• If creating an ingress, the URL_BASE value is the DNS defined to hook into the ingress, such as https://company.dev.instabase.com.

  • For example, to use the Database configuration API, POST to https://company.dev.instabase.com/api/v1/control_plane/installer/db.

Responses

All Installer API endpoints (with the exception of Get the status of post-install actions) use the same response format:

• The response body is a JSON object.

• A statusCode of 200 indicates success. No additional information is returned in the data or error keys. For example:

  {
    "statusCode": 200,
    "data": null,
    "error": null
  }
  

• A statusCode of 500 indicates an error. The response body contains parameter-specific error information under the error key, if applicable. For example:

  {
    "statusCode": 500,
    "data": {
        "note": "",
        "ok": false
    },
    "error": "http conn serve: http conn serve: kubernetes client is nil"
  }
  

Authentication

In this document {TOKEN} defines the Deployment Manager token.

All API requests must include your valid Deployment Manager token to authenticate the request.The Deployment Manager API Token is created in the cluster with a default, changeable value when the Deployment Manager YAML is applied.

To fetch the Deployment Manager API token, run the following command in the command line:

export TOKEN=$(kubectl -n $IB_NS get \
secret/control-plane-metadata \
--template={{.data.api_token}} | base64 -d)

You can then reference the token in your calls using $TOKEN in place of {TOKEN}.

Database configuration

Description

This API configures the connection to your relational database. The database contains all the metadata needed to run Instabase. This includes information for user accounts, repositories, organizations, access control, Marketplace solutions, and more.

Instabase supports connecting to the following databases:

• MySQL

• PostgreSQL

• Microsoft SQL Server

  • Connecting with username and password credentials

  • Connecting with Azure AD credentials

• Oracle

MySQL

Request parameters

The general form of the request body is:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/db' \
--header 'Accept: application/json, text/plain, */*' \
--header 'Token: {TOKEN}' \
--data-raw '{DB_REQ_BODY}' \
--compressed

Your database configuration details are outlined in the DB_REQ_BODY object. The following parameters are required, unless marked as optional:

Examples

Request example:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/db' \
--header 'Accept: application/json, text/plain, */*' \
--header 'Token: {TOKEN}' \
--data-raw '{
  "skip_db_setup": false,
  "db_type": "mysql",
  "azure_ad": false,
  "use_db_sid": false,
  "use_db_service_name": false,
  "enable_db_tls": false,
  "fields": {
    "db_user": "root",
    "db_pass": "{password}",
    "db_name": "ibdb",
    "db_host": "service-mysql.instabase.svc.cluster.local",
    "db_port": 3306
    }
  }' \
--compressed

PostgreSQL

Request parameters

The general form of the request body is:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/db' \
--header 'Accept: application/json, text/plain, */*' \
--header 'Token: {TOKEN}' \
--data-raw '{DB_REQ_BODY}' \
--compressed

Your database configuration details are outlined in the DB_REQ_BODY object. The following parameters are required, unless marked as optional:

Request example:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/db' \
--header 'Accept: application/json, text/plain, */*' \
--header 'Token: {TOKEN}' \
--data-raw '{
  "skip_db_setup": false,
  "db_type": "postgres",
  "azure_ad": false,
  "use_db_sid": false,
  "use_db_service_name": false,
  "enable_db_tls": false,
  "fields": {
    "db_user": "test-user",
    "db_pass": "test-pass",
    "db_name": "test-db-name",
    "db_host": "test-host",
    "db_port": 1234,
    "ssl_mode": "disable"
    }
  }' \
--compressed

Microsoft SQL Server: Connect with username and password

Request parameters

The general form of the request body is:

curl --location --request POST  '{URL_BASE}/api/v1/control_plane/installer/db' \
--header 'Accept: application/json, text/plain, */*' \
--header 'Token: {TOKEN}' \
--data-raw '{DB_REQ_BODY}' \
--compressed

Your database configuration details are outlined in the DB_REQ_BODY object. The following parameters are required, unless marked as optional:

Examples

Request example:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/db' \
--header 'Accept: application/json, text/plain, */*' \
--header 'Token: {TOKEN}' \
--data-raw '{
  "skip_db_setup": false,
  "db_type": "sqlserver",
  "azure_ad": false,
  "use_db_sid": false,
  "use_db_service_name": false,
  "enable_db_tls": true,
  "fields": {
    "db_user": "test-user",
    "db_pass": "test-pass",
    "db_name": "test-db-name",
    "db_host": "test-host",
    "db_port": 1234,
    "db_conn_timeout": 30
    }
  }' \
--compressed

Microsoft SQL Server: Connect with Azure AD

Request parameters

The general form of the request body is:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/db' \
--header 'Accept: application/json, text/plain, */*' \
--header 'Token: {TOKEN}' \
--data-raw '{DB_REQ_BODY}' \
--compressed

Your database configuration details are outlined in the DB_REQ_BODY object. The following parameters are required, unless marked as optional:

Examples

Request example:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/db' \
--header 'Accept: application/json, text/plain, */*' \
--header 'Token: {TOKEN}' \
--data-raw '{
  "skip_db_setup": false,
  "db_type": "sqlserver",
  "azure_ad": true,
  "use_db_sid": false,
  "use_db_service_name": false,
  "enable_db_tls": true,
  "fields": {
    "db_name": "test-db-name",
    "db_host": "test-host",
    "db_port": 1234,
    "db_conn_params": "Connection Timeout=30;ConnectRetryCount=3;ConnectRetryInterval=10",
    "db_azure_tenant_id": "azure-tenant-id",
    "db_azure_client_id": "azure-client-id",
    "db_azure_client_secret": "azure-secret"
    }
  }' \
--compressed

Oracle

Request parameters

The general form of the request body is:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/db' \
--header 'Accept: application/json, text/plain, */*' \
--header 'Token: {TOKEN}' \
--data-raw '{DB_REQ_BODY}' \
--compressed

Your database configuration details are outlined in the DB_REQ_BODY object. The following parameters are required, unless marked as optional:

Examples

Request example if using the database name as the database identifier:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/db' \
--header 'Accept: application/json, text/plain, */*' \
--header  'Token: {TOKEN}' \
--data-raw '{
  "skip_db_setup": false,
  "db_type": "oci8",
  "azure_ad": false,
  "use_db_sid": false,
  "use_db_service_name": false,
  "enable_db_tls": false,
  "fields": {
    "db_user": "test-user",
    "db_pass": "test-pass",
    "db_name": "normal-db-name",
    "db_host": "test-host",
    "db_port": 1234
    }
  }' \
--compressed

Request example if using the SID as the database identifier:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/db' \
--header 'Accept: application/json, text/plain, */*' \
--header 'Token: {TOKEN}' \
--data-raw '{
  "skip_db_setup": false,
  "db_type": "oci8",
  "azure_ad": false,
  "use_db_sid": true,
  "use_db_service_name": false,
  "enable_db_tls": false,
  "fields": {
    "db_user": "test-user",
    "db_pass": "test-pass",
    "db_name": "",
    "db_host": "test-host",
    "db_port": 1234,
    "db_sid": "db sid"
    }
  }' \
--compressed

Request example if using the service name as the database identifier:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/db' \
--header 'Accept: application/json, text/plain, */*' \
--header 'Token: {TOKEN}' \
--data-raw '{
  "skip_db_setup": false,
  "db_type": "oci8",
  "azure_ad": false,
  "use_db_sid": false,
  "use_db_service_name": true,
  "enable_db_tls": false,
  "fields": {
    "db_user": "test-user",
    "db_pass": "test-pass",
    "db_name": "",
    "db_host": "test-host",
    "db_port": 1234,
    "db_service_name": "service name"
    }
  }' \
--compressed

Database connection string format

If skip_db_setup is enabled, you must create a Kubernetes secret that contains a database connection string with the required parameters. Refer to the following table for guidance on how to format the database connection string:

TLS authentication configuration

Description

Configures SSL certificates in Deployment Manager, for databases using TLS authentication for database connections. This endpoint is required only if enable_db_tls was set to true when configuring your database configuration.

MySQL

Request parameters

The following parameters are required, unless marked as optional:

Examples

Request example:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/db/tls' \
--header 'Content-Type: multipart/form-data' \
--header 'Token: {TOKEN}' \
--form 'db_tls_client_key=@"/path/to/file"' \
--form 'db_tls_client_cert=@"/path/to/file"' \
--form 'db_tls_root_cert=@"/path/to/file"' \
--form 'db_tls_cert_hostname="hostname"' \
--form 'db_tls_skip_verify="False"'

PostgreSQL

Request parameters

The following parameters are required, unless marked as optional:

Examples

Request example:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/db/tls' \
--header 'Content-Type: multipart/form-data' \
--header 'Token: {TOKEN}' \
--form 'db_tls_root_cert=@"/path/to/file"' \
--form 'db_tls_client_key=@"/path/to/file"' \
--form 'db_tls_client_cert=@"/path/to/file"' \
--form 'db_tls_root_crl=@"/path/to/file"'

Microsoft SQL Server

Request parameters

The following parameters are required, unless marked as optional:

Examples

Request example:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/db/tls' \
--header 'Content-Type: multipart/form-data' \
--header 'Token: {TOKEN}' \
--form 'ss_cert=@"/path/to/file"' \
--form 'ss_trust_server_cert="False"' \
--form 'ss_cert_hostname="hostname"'

File system configuration

Description

This API configures the connection to your file storage provider. Instabase Installer supports four file storage options:

• Amazon S3
• Local file storage
• Azure Blob Storage
• Google Cloud Storage

Amazon S3

Request parameters

The general form of the request body is:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/storage' \
--header 'Token: {TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{STORAGE_REQ_BODY}'

Your database configuration details are outlined in the STORAGE_REQ_BODY object. The following parameters are required, unless marked as optional:

Examples

Request example:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/storage' \
--header 'Token: {TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "file_storage": "s3",
    "fields": {
        "s3_server_url": "test-server-url",
        "s3_server_is_secure": true,
        "s3_access_key_id": "test-access-key",
        "s3_secret_access_key": "test-secret-key",
        "s3_aws_region": "us-east-1",
        "s3_bucket_name": "test-bucket-name",
        "s3_encryption_type": "none",
        "s3_use_virtual_style_url": "true",
        "enable_file_cache": true
      }
  }'

Local file storage

Instabase supports using a network file system (NFS) as your file storage. For security reasons, however, Instabase does not support directly connecting to the NFS. You must first mount your NFS as a Kubernetes Persistent Volume Claim (PVC).

Request parameters

The general form of the request body is:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/storage' \
--header 'Token: {TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw  '{STORAGE_REQ_BODY}'

Your database configuration details are outlined in the STORAGE_REQ_BODY object. The following parameters are required, unless marked as optional:

Examples

Request example:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/storage' \
--header 'Token: {TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "file_storage": "localfs",
    "fields": {
        "local_mount_dir": "/home/ibuser/data",
        "nfs_pvc_name": "test-pvc",
        "enable_file_cache": true
      }
  }'

Azure Blob Storage

Request parameters

The general form of the request body is:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/storage' \
--header 'Token: {TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw  '{STORAGE_REQ_BODY}'

Your database configuration details are outlined in the STORAGE_REQ_BODY object. The following parameters are required, unless marked as optional:

Examples

Request example:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/storage' \
--header 'Token: {TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "file_storage": "azblobstore",
    "fields": {
        "azure_connection_str": "test-connection-string",
        "az_blob_store_container": "test-container-name",
        "enable_file_cache": true
      }
  }'

Google Cloud Storage

Request parameters

The general form of the request body is:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/storage' \
--header 'Token: {TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{STORAGE_REQ_BODY}'

Your database configuration details are outlined in the STORAGE_REQ_BODY object. The following parameters are required, unless marked as optional:

Examples

Request example:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/storage' \
--header 'Token: {TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "file_storage": "googlecloudstorage",
    "fields": {
        "bucket_name": "dummy-bucket",
        "gcs_sse_encryption_type": "gcs_aes256",
        "gcs_sse_kms_key_id": "",
        "enable_file_cache": true
      }
  }'

Upload custom Amazon S3 certificate

This API uploads a custom certificate for SSL verification, if required by your S3 server. Complete this API call after configuring Amazon S3 as your file storage.

Request parameters

The general form of the request body is:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/storage/cert' \
--header 'Token: {TOKEN}' \
--header 'Content-Type: multipart/form-data' \
--form 's3_cert=@"/path/to/file"'

Examples

Request example:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/storage/cert' \
--header 'Token: {TOKEN}' \
--header 'Content-Type: multipart/form-data' \
--form 's3_cert=@"/path/to/file"'

Upload Google Cloud Storage service account credentials

Description

This API uploads the service account credentials file for your Google Cloud Storage account. This API must be called before configuring Google Cloud Storage as your file storage.

Request parameters

The following parameters are required, unless marked as optional:

Configuring the Google Cloud Storage service account

To configure a Google Cloud Storage service account:

1. From the Google Cloud console, create a Google Cloud Storage bucket with uniform access control. For improved security, create it as a private bucket.

2. Create a service account in Google Cloud’s Identity and Access Management (IAM) system.

3. In the Google Cloud console, create a key pair for the service account, selecting JSON as the key type.

4. Download the JSON credentials file for the service account.

5. Assign the service account the Storage Admin and Storage Object Admin roles for bucket access.

   Info

   More detailed instructions can be found in the Google IAM permission documentation.

6. Find the Client ID for the service account (available on the Service accounts page).

7. Using a Google Workplace administrator account, search for the service account’s client ID, and grant the service account access to the Google Cloud Platform OAuth scope www.googleapis.com/auth/cloud-platform.

   Info

   More detailed instructions can be found in the Google Service account documentation.

Examples

Request example:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/storage/gcsserviceaccount' \
--header 'Token: {TOKEN}' \
--header 'Content-Type: application/json' \
--form 'gcs_service_account_credentials=@"/path/to/gcscredentials.json"'

Configure platform and Kubernetes cluster-related settings

Description

This API configures platform and Kubernetes cluster-related settings, including admin login credentials and Persistent Volume Claim names.

Request parameters

The following parameters are required, unless marked as optional:

Examples

Request example:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/other' \
--header 'Token: {TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "namespace": "instabase",
    "admin_username": "test-user",
    "admin_email": "test@email.com",
    "admin_password": "password",
    "admin_password_confirmation": "password"
  }'

Configure Kubernetes cluster resourcing

Description

This API sets the Kubernetes cluster resourcing size. The following preset cluster size options are available:

• standard: 64 CPU cores/256 GB RAM
• large: 128 CPU cores/512 GB RAM
• xlarge: 256 CPU cores/1024 GB RAM

Select the option that meets but does not exceed your cluster size defined in Kubernetes. After installation, you can manually adjust the Instabase cluster size configuration using patches to more closely match your Kubernetes cluster size.

Request parameters

The following parameters are required, unless marked as optional:

Examples

Request example:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/resourcing' \
--header 'Token: {TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "cluster_size": "standard"
}'

Preflight checks

Preflight checks validate your information to assess if installation can proceed. These checks are optional and require no parameter configuration, but they are helpful to verify that your infrastructure is set up correctly and is accessible.

The following checks are available:

• Service accounts check

• Role-based access control (RBAC) check

• Persistent Volume Claim (PVC) check

• File storage access check

• Database check

Service accounts check

Description

This check confirms the service account used by the Instabase observability monitoring services exists in the Kubernetes cluster.

Request

There are no customizable parameters. Make the following request, using your own URL_BASE and TOKEN values:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/preflight/checks/service_accounts' \
--header 'Token: {TOKEN}' \
--header 'Content-Type: application/json' \

Role-based access control (RBAC) check

Description

This check reports back any inconsistencies between permissions the Deployment Manager service account requires and permissions it has been granted. A success message indicates the Kubernetes role resource associated with the Deployment Manager service account matches the permissions Deployment Manager requires. A failure message shows the expected configuration alongside the configuration found in the cluster.

Request

There are no customizable parameters. Make the following request, using your own URL_BASE and TOKEN values:

curl --location --request 'POST {URL_BASE}/api/v1/control_plane/installer/preflight/checks/rbac' \
--header 'Token: {TOKEN}' \
--header 'Content-Type: application/json' \

File storage access check

Description

This check tests that the file system credentials entered can connect to your file storage platform. This check also verifies that Instabase has the permissions needed to perform all necessary file operations.

Request

There are no customizable parameters. Make the following request, using your own URL_BASE and TOKEN values:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/preflight/checks/file_storage_access' \
--header 'Token: {TOKEN}' \
--header 'Content-Type: application/json' \

Database check

Description

This check tests that the database credentials entered can connect to your database. This check also verifies that Instabase has appropriately scoped permissions for table creation, table reading, and table writing.

Request

There are no customizable parameters. Make the following request, using your own URL_BASE and TOKEN values:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/preflight/checks/database' \
--header 'Token: {TOKEN}' \
--header 'Content-Type: application/json' \

Persistent Volume Claim (PVC) check

Description

This check tests that all required PVCs are present, bound, and mountable.

Request

There are no customizable parameters. Make the following request, using your own URL_BASE and TOKEN values:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/preflight/checks/pvc' \
--header 'Token: {TOKEN}' \
--header 'Content-Type: application/json' \

Upload Instabase license

Description

This API uploads your Instabase license. Your license is provided by your customer success manager and is an .iblicense file.

Request parameters

The following parameters are required, unless marked as optional:

Examples

Request example:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/license' \
--header 'Token: {TOKEN}' \
--form 'file=@"/path/to/license.iblicense"'

Upload base configurations

Description

This API uploads your Instabase base configurations. The base configurations file, called base_configs.zip, is in the release’s installation.zip file.

Request parameters

The following parameters are required, unless marked as optional:

Examples

Request example:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/baseconfig' \
--header 'Content-Type: multipart/form-data' \
--header 'Token: {TOKEN}' \
--form 'file=@"/path/to/baseconfig.zip"'

Upload default patches

Description

This API uploads the required default patches to apply during installation. The default patches file is called default_patches.zip and is found in the installation.zip file.

The default_patches.zip file contains all patches that must be uploaded during installation, but you can optionally add additional patches to apply during installation. Any new patches must be added alongside the contents of the default_patches.zip file:

1. Unzip the installation.zip file.
2. Unzip the default_patches.zip file contained within the now unzipped installation folder.
3. Add any new custom patch files to the now unzipped default_patches folder.
4. Select all files in the default_patches folder and compress them, creating a new .zip file of patches. You can rename the .zip file, but there are no file name requirements.

This new .zip file is what you pass in the request.

Request parameters

The following parameters are required, unless marked as optional:

Examples

Request example:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/defaultpatches' \
--header 'Content-Type: multipart/form-data' \
--header 'Token: {TOKEN}' \
--form 'file=@"/path/to/defaultpatches.zip"'

Upload network policies

Description

This optional API uploads any network policies to apply during installation. If indicated, your installation.zip package includes a folder called network-policies containing a series of network policy files. After making any necessary changes to the network policy files, compress the network-policies folder.

Request parameters

Examples

Request example:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/network-policies' \
--header 'Content-Type: multipart/form-data' \
--header 'Token: {TOKEN}' \
--form 'file=@"/path/to/defaultnetworkpolicies.zip"'

Create SAML configuration

Description

This API creates a security assertion markup language (SAML) configuration. Instabase supports SAML-based authentication to manage access to your Instabase deployment. Using SAML-based single sign-on (SSO) lets you leverage your existing SSO identity provider (IdP) to automatically create new user accounts on the Instabase platform upon initial login. You can also optionally map existing groups configured in your IdP to groups in your Instabase deployment.

Instabase uses service provider (SP)-initiated SSO authentication and supports IdPs that use SAML 2.0.

Creating a SAML connection is an optional part of installation. You can also create a SAML connection after installation is complete. The APIs used to complete a SAML connection are:

• Create SAML configuration: Creates the SAML configuration.

• (Optional) Upload IdP metadata XML: Uploads the IdP metadata XML file, if using local metadata access. If using remote metadata access, this call is not required.

• Complete SAML configuration: Completes the SAML configuration connection.

  Note

  If configuring the SAML connection during installation, call the complete SAML configuration API only after installation is complete.

• (Optional) Clear SAML configuration If needed, before completing the configuration, you can clear the latest configuration posted using the create SAML configuration API.

Request parameters

The following parameters are required, unless marked as optional:

Examples

Request example:

curl --location '{URL_BASE}/api/v1/control_plane/installer/saml/config' \
--header 'token: {TOKEN}' \
--header 'Content-Type: application/json' \
--data '{
    "configureSaml": true,
    "authProvider": "remote",
    "authProviderUri": "http://authprovider.com/metadata-server-endpoint",
    "requiredAttributes": "email, uid",
    "optionalAttributes": "groups",
    "spEntityId": "https://client-dev.instabase.com",
    "spName": "InstabaseSP",
    "httpAcsUrl": "https://client.instabase.com/account/sso/saml2",
    "httpsAcsUrl": "http://client.instabase.com/account/sso/saml2",
    "allowUnsolicited": true,
    "authRequestsSigned": false,
    "logoutRequestsSigned": true,
    "wantAssertionsSigned": true,
    "wantResponseSigned": true
}'

Upload IdP metadata XML

Description

This API uploads the IdP metadata XML file for the SAML connection. This API is required if the auth_provider field in the create SAML configuration request is set to local.

When the complete SAML configuration API is called, a Kubernetes secret containing this metadata file is created. The secret is what is referenced during SAML authentication.

Request parameters

The following parameters are required, unless marked as optional:

Examples

Request example:

curl --location '{URL_BASE}/api/v1/control_plane/installer/saml/metadata' \
--header 'token: {TOKEN}' \
--form 'samlMetadata=@"/Users/janedoe/metadata.xml"'

Clear SAML configuration

Description

This API lets you clear the SAML configuration most recently posted using the create SAML configuration and upload IdP metadata XML APIs. This API has no effect if the complete SAML configuration API has been called. This API clears only unfinished configurations, it does not delete completed SAML connections.

Request

There are no customizable parameters. Make the following request, using your own URL_BASE and TOKEN values:

curl --location --request DELETE '{URL_BASE}/api/v1/control_plane/installer/saml' \
--header 'Token: {TOKEN}'

Finalize installation

Description

This API initiates installation. If an installation is unsuccessful, this API is also used to retry installation.

Request parameters

The following parameters are required, unless marked as optional:

Examples

Request example:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/finalize' \
--header 'Token: {TOKEN}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'clean_install=true'

Complete SAML configuration

Description

This API completes the SAML configuration connection, using the configuration (and, if present, IdP metadata XML) most recently posted using the create SAML configuration and upload IdP metadata XML APIs.

Request

There are no customizable parameters. Make the following request, using your own URL_BASE and TOKEN values:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/installer/saml' \
--header 'Token: {TOKEN}'

Run post-install actions

Description

This API initiates post-install actions. The API needs to be called only once, after installation has completed.

The simplest way to confirm a successful installation is to use the Deployment Manager infra dashboard. From the infra dashboard, you can view the state of various components of your Kubernetes infrastructure. You can access the infra dashboard at {YOUR-INSTABASE-URL}/deployment-manager/dashboard/deployments.

Use the dashboard tabs to see which Deployments, StatefulSets, and Services have spun up and are working as expected. Items with a green checkmark are ready to use, items with a spinning icon are still spinning up, and items with a red X have encountered an error or other event. If any deployments display a red X, you can connect with Instabase Support for next steps, and provide events history and logs for the affected pods and containers.

After confirming a successful installation, you can run the following post-install actions:

• Base model image upload action: Downloads all Instabase base models required for running ML Studio offline training, along with numerous entity detection models, and publishes them to the Marketplace so they’re ready to use.

• Deployed Solutions consistency action: Migrates Deployed Solutions published on releases < 23.07, to ensure compatibility with the current Instabase version.

• License action: Applies the license uploaded to Instabase Installer.

• ML Studio config setup action: Performs the post-deployment configuration of ML Studio using the latest version of the .ibformers training script.

• Setup system retention rules: Sets up system-level rules used to support user-defined file retention settings (only applicable to SaaS deployments).

• System repo setup action: Sets up backing file system infrastructure required to publish new models to the platform.

• Test Runner setup action: Sets up a Test Runner test suite used in the Test Runner test action. The test suite includes a variety of tasks commonly performed with the Instabase platform, providing broad coverage of expected functionality. Tested functionality includes:

  • Verify solutions (including flows, flow binaries, and .ibsolutions) can successfully run end-to-end.

  • Verify a variety of common input file types can be processed successfully.

  • Assess the performance of a variety of Instabase components, including apps and services.

  • Assess the performance of a variety of OCR engines.

• Test Runner test action: Runs the Test Runner test suite set up in the previous action. When complete, solution diagnostics display for each test, including a status for the test and comparison details if expected (base_value) and actual (compare_value) solution results differ.

  Info

  The test suite includes tests that assess the performance of a variety of OCR engines. If your deployment does not use a given OCR engine, that test will result in an error. Connect with your customer success manager if you have any questions or concerns about a failed test.

If your post-install actions encounter errors and fail (see the Get the status of post-install actions API), this API can also be used to retry running all post-install actions, after the source of error has been resolved.

Request

There are no customizable parameters. Make the following request, using your own URL_BASE and TOKEN values:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/deployment/postinstall/actions/run' \
--header 'Token: {TOKEN}'

Run a single post-install action

Description

Use this API to run a single post-install action. This API can be used if, after calling the Run post-install actions API, a single post-install action has failed but its dependencies completed successfully. If the failed action’s dependencies did not complete successfully, rerun the Run post-install actions API, rather than the single failed action.

After confirming a successful installation, you can run the following post-install actions, using the corresponding URL-encoded ACTION-NAME value in the request URL:

Request

Make the following request, using your own URL_BASE, TOKEN, and ACTION_NAME values:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/deployment/postinstall/actions/run/{ACTION_NAME}' \
--header 'Token: {TOKEN}'

Get the status of post-install actions

Description

This API gets the status of post-install actions initiated using the Run post-install actions API. Completing the post-install actions takes some time.

Request

There are no customizable parameters. Make the following request, using your own URL_BASE and TOKEN values:

curl --location '{URL_BASE}/api/v1/control_plane/deployment/postinstall/actions/statuses' \
--header 'Token: {TOKEN}'

Response

The response is a JSON object, with the following keys:

Examples

Sample response with no errors running post-install actions:

{
  "statusCode": 200,
  "data": {
    "Base Model Image Upload Action": {
      "State": "Unstarted",
      "Note": "Action is not started yet."
    },
    "License Action": {
      "State": "Running",
      "Note": "License upload has started."
    },
    "ML Studio Config Setup Action": {
      "State": "Unstarted",
      "Note": "ML studio config setup action has not started."
    },
    "System Repo Setup Action": {
      "State": "Running",
      "Note": "System repo setup has started."
    }
  },
  "error": null
}

Sample response with errors running post-install actions:

{
  "statusCode": 200,
  "data": {
    "Base Model Image Upload Action": {
      "State": "Aborted",
      "Note": "actions base model image upload action wait for dependencies: dependency is in Aborted state"
    },
    "License Action": {
      "State": "Aborted",
      "Note": "actions license action license: actions license action decrypt: Post \"http://service-api-server.instabase.svc.cluster.local:25555/api/v1/license-service/preview\": dial tcp: lookup service-api-server.instabase.svc.cluster.local: no such host"
    },
    "ML Studio Config Setup Action": {
      "State": "Aborted",
      "Note": "dependency is in Aborted state"
    },
    "System Repo Setup Action": {
      "State": "Aborted",
      "Note": "actions system repo setup action setup system repo: Post \"http://service-api-server.instabase.svc.cluster.local:25555/api/v1/site/setup-system-repo\": dial tcp: lookup service-api-server.instabase.svc.cluster.local: no such host"
    }
  },
  "error": null
}

Sample response with error getting statuses:

{
  "statusCode": 500,
  "data": {},
  "error": "GetActionStatuses: http conn serve: actionHelper.GetActionData: RegistryManager.GetActionData: RegistryManager.getValue: Error 1146 (42S02): Table 'ibdb.key_values' doesn't exist"
}

Roll back all post-install actions

Description

This API undoes the operations of the most recent runs of all of the following actions:

• Base model image upload action

• Deployed Solutions consistency action

• ML Studio set up action

Only use this API if the most recent run of one of these actions has caused undesirable platform behavior.

Request

Make the following request, using your own URL_BASE and TOKEN values:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/deployment/postinstall/actions/rollback' \
--header 'Token: {TOKEN}'

Set the status of a single post-install action

Description

Use this API to manually reset the status of a post-install action initiated using the Run post-install actions API. This API is used when Deployment Manager has crashed during the execution of a post-install action. In this situation, the status tracking of the running action can become corrupted, and the action’s status must be reset to unstarted. When Deployment Manager comes up again after crashing, use this API to reset any action showing a status of in progress. When all actions show a state of unstarted, you can rerun the Run post-install actions API.

Each in progress action must be reset individually. To specify the action to reset, pass the action’s corresponding ACTION_ID value in the request URL. Valid ACTION_ID values are listed:

{"state":"Unstarted","note":"Action status set manually.","executionId":"00000000-0000-0000-0000-000000000000"}

Request

Make the following request, using your own URL_BASE, TOKEN, and ACTION_ID values:

curl --location --request POST '{URL_BASE}/api/v1/control_plane/deployment/postinstall/actions/statuses/{ACTION_ID}' \
--header 'Token: {TOKEN}' \
--data '{"state":"Unstarted","note":"Action status set manually.","executionId":"00000000-0000-0000-0000-000000000000"}'