Configure an Amazon Redshift Spectrum Integration

In the Amazon Redshift Spectrum integration, Immuta generates policy-enforced views in your configured Redshift schema for tables registered as Immuta data sources.

Use the /integrations endpoint to

• configure an Amazon Redshift Spectrum integration

• get an Amazon Redshift Spectrum integration

• get all integrations

• update an Amazon Redshift Spectrum integration

• delete an Amazon Redshift Spectrum integration

Requirements

• A Redshift cluster with an AWS row-level security patch applied. Contact Immuta for guidance.

• An AWS IAM role for Redshift that is associated with your Redshift cluster.

• The enable_case_sensitive_identifier parameter must be set to false (default setting) for your Redshift cluster.

• A Redshift database that contains an external schema and external tables.

Permissions

The user configuring the integration must have the permissions below.

• APPLICATION_ADMIN Immuta permission

• The Redshift role used to run the Immuta bootstrap script must have the following privileges when configuring the integration:

  • If using an existing database

    • ALL PRIVILEGES ON DATABASE for the database you configure the integration with, as you must manage grants on that database.

    • CREATE USER

    • GRANT TEMP ON DATABASE

  • If creating a new database

    • CREATE DATABASE

    • CREATE USER

    • GRANT TEMP ON DATABASE

    • REVOKE ALL PRIVILEGES ON DATABASE

Configure the integration

To configure the integration, complete the following steps:

1. Set up an Immuta database in Amazon Redshift.

2. Generate the Immuta script and run it inside the database you created.

3. Configure the integration in Immuta.

Setup the Immuta database

You have two options for setting up the database Immuta will use to manage the integration and enforce policies:

• Configure the integration with an existing database that contains the external tables. When configuring the integration, specify an existing database in Amazon Redshift as the database in which Immuta will add the Immuta-managed schemas and views.

  If using an existing database, the Redshift role used to run the Immuta bootstrap script must have the following privileges:

  • ALL PRIVILEGES ON DATABASE for the database you configure the integration with, as you must manage grants on that database.

  • CREATE USER

  • GRANT TEMP ON DATABASE

• Create a new database: Create a new database for Immuta that manages all schemas and views created when Redshift data is registered in Immuta, and re-create all of your external tables in that database. When configuring the integration, specify this new database you created in Amazon Redshift as the database in which Immuta will add the Immuta-managed schemas and views. If creating a new database, the Redshift role used to run the Immuta bootstrap script must have the following privileges:

  • CREATE DATABASE

  • CREATE USER

  • GRANT TEMP ON DATABASE

  • REVOKE ALL PRIVILEGES ON DATABASE

Generate the script

curl -X 'POST' \
    'https://www.organization.immuta.com/integrations/scripts/create' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Redshift",
    "autoBootstrap": false,
    "config": {
      "host": "organization.aws.amazon.com",
      "database": "immuta",
      "impersonation": {
        "enabled": false
      },
      "authenticationType": "userPassword",
      "username": "[email protected]",
      "password": "abc1234"
    }
    }'

1. Copy the request example. The example provided uses JSON format, but the request also accepts YAML.

2. Replace the Immuta URL and API key with your own.

3. Change the config values to your own, where

   • host is the URL of your Redshift account.

   • database is the name of the existing or new database that the Immuta system user will manage and store metadata in.

   • impersonation specifies whether user impersonation is enabled. See the object description for child parameters.

   • username and password are the credentials for the system account that can act on Redshift objects and configure the integration.

4. Run the script returned in the response in the existing or new database you created in Amazon Redshift.

See the config object description for parameter definitions, value types, and additional configuration options.

Response

The response returns the script for you to run in the existing or new database you created for the Immuta system user.

Configure the integration in Immuta

curl -X 'POST' \
    'https://www.organization.immuta.com/integrations' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Redshift",
    "autoBootstrap": false,
    "config": {
      "host": "organization.aws.amazon.com",
      "database": "immuta",
      "impersonation": {
        "enabled": false
      },
      "authenticationType": "userPassword",
      "username": "[email protected]",
      "password": "abc1234"
    }
    }'

1. Copy the request example. The example provided uses JSON format, but the request also accepts YAML.

2. Replace the Immuta URL and API key with your own.

3. Pass the same payload you sent when generating the script, where

   • host is the URL of your Redshift account.

   • database is the name of the existing or new database that the Immuta system user will manage and store metadata in.

   • impersonation specifies whether user impersonation is enabled. See the object description for child parameters.

   • username and password are the credentials for the system account that can act on Redshift objects and configure the integration.

See the config object description for parameter definitions, value types, and additional configuration options.

Response

The response returns the status of the Amazon Redshift Spectrum integration configuration connection. See the response schema reference for details about the response schema.

200 response

A successful response includes the validation tests statuses.

{
  "id": "123456789",
  "status": "creating",
  "validationResults": {
    "status": "passed",
    "validationTests": [
    {
      "name": "Initial Validation: Basic Connection Test",
      "result": [null],
      "status": "passed"
    },
    {
      "name": "Validate Automatic: Immuta Database Does Not Exist",
      "result": [],
      "status": "passed"
    }
    ]
  }
}

Unsuccessful response

Get an integration

curl -X 'GET' \
    'https://www.organization.immuta.com/integrations/{id}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f'

1. Copy the request example.

2. Replace the Immuta URL and API key with your own.

3. Replace the {id} request parameter with the unique identifier of the integration you want to get. Alternatively, you can get a list of all integrations and their IDs with the GET /integrations endpoint.

Response

The response returns an Amazon Redshift Spectrum integration configuration. See the response schema reference for details about the response schema. An unsuccessful request returns the status code and an error message. See the HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.

{
  "id": "123456789",
  "status": "enabled",
  "validationResults": {
    "status": "passed",
    "validationTests": [
    {
      "name": "Initial Validation: Basic Connection Test",
      "result": [null],
      "status": "passed"
    },
    {
      "name": "Validate Automatic: Immuta Database Does Not Exist",
      "result": [],
      "status": "passed"
    }
    ]
  },
  "type": "Redshift",
  "autoBootstrap": false,
  "config": {
    "host": "organization.aws.amazon.com",
    "database": "immuta",
    "port": 5439,
    "impersonation": {
      "enabled": false
    },
    "authenticationType": "userPassword",
    "username": "<REDACTED>",
    "password": "<REDACTED>"
  }
}

Get all integrations

curl -X 'GET' \
    'https://www.organization.immuta.com/integrations' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f'

1. Copy the request example.

2. Replace the Immuta URL and API key with your own.

Response

The response returns the configuration for all integrations. See the response schema reference for details about the response schema. An unsuccessful request returns the status code and an error message. See the HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.

[
  {
    "id": "1",
    "status": "enabled",
    "validationResults": {
      "status": "passed",
      "validationTests": [
        {
          "name": "Initial Validation: Basic Connection Test",
          "status": "passed"
        },
        {
          "name": "Initial Validation: Default Warehouse Access Test",
          "status": "passed",
          "result": []
        },
        {
          "name": "Initial Validation: Validate access to Privileged Role",
          "status": "passed",
          "result": []
        },
        {
          "name": "Validate Automatic: Database Does Not Exist",
          "status": "passed"
        },
        {
          "name": "Validate Automatic: Impersonation Role Does Not Exist",
          "status": "skipped"
        },
        {
          "name": "Validate Automatic: User Grants",
          "status": "passed"
        }
      ]
    },
    "type": "Snowflake",
    "autoBootstrap": true,
    "config": {
      "host": "organization.us-east-1.snowflakecomputing.com",
      "warehouse": "SAMPLE_WAREHOUSE",
      "database": "SNOWFLAKE_SAMPLE_DATA",
      "port": 443,
      "audit": {
        "enabled": false
      },
      "workspaces": {
        "enabled": false
      },
      "impersonation": {
        "enabled": false
      },
      "lineage": {
        "enabled": false
      },
      "authenticationType": "userPassword",
      "username": "<REDACTED>",
      "password": "<REDACTED>",
      "role": "ACCOUNTADMIN"
    }
  },
  {
    "id": "2",
    "status": "enabled",
    "type": "Databricks",
    "validationResults": {
      "status": "passed",
      "validationTests": [
        {
          "name": "Metastore validation",
          "status": "passed"
        },
        {
          "name": "Basic Connection Test",
          "result": [
            {
              "1": 1
            }
          ],
          "status": "passed"
        }
      ]
    },
    "autoBootstrap": true,
    "config": {
      "workspaceUrl": "www.example-workspace.cloud.databricks.com",
      "httpPath": "sql/protocolv1/o/0/0000-00000-abc123",
      "token": "REDACTED",
      "audit": {
        "enabled": false
      },
      "catalog": "immuta"
    }
  }
]

Update an integration configuration

To update the integration, complete the following steps:

1. Generate the updated Immuta script and run it in your Redshift environment.

2. Update the integration in Immuta.

Generate the updated script

curl -X 'POST' \
    'https://www.organization.immuta.com/integrations/{id}/scripts/edit' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Redshift",
    "autoBootstrap": false,
    "config": {
      "host": "organization.aws.amazon.com",
      "database": "immuta",
      "impersonation": {
        "enabled": false
      },
      "authenticationType": "userPassword",
      "username": "[email protected]",
      "password": "abc1234"
    }
    }'

1. Copy the request example. The example provided uses JSON format, but the request also accepts YAML.

2. Replace the Immuta URL and API key with your own.

3. Replace the {id} request parameter with the unique identifier of the integration you want to update.

4. Change the config values to your own, where

   • host is the URL of your Redshift account.

   • database is the name of the existing or new database that the Immuta system user will manage and store metadata in.

   • impersonation specifies whether user impersonation is enabled. See the object description for child parameters.

   • username and password are the credentials for the system account that can act on Redshift objects and configure the integration.

5. Run the script returned in the response in your Amazon Redshift environment.

See the config object description for parameter definitions, value types, and additional configuration options.

Response

The response returns the script for you to run in your Amazon Redshift environment.

Update the integration in Immuta

curl -X 'PUT' \
    'https://www.organization.immuta.com/integrations/{id}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Redshift",
    "autoBootstrap": false,
    "config": {
      "host": "organization.aws.amazon.com",
      "database": "immuta",
      "impersonation": {
        "enabled": false
      },
      "authenticationType": "userPassword",
      "username": "[email protected]",
      "password": "abc1234"
    }
    }'

1. Copy the request example. The example provided uses JSON format, but the request also accepts YAML.

2. Replace the Immuta URL and API key with your own.

3. Replace the {id} request parameter with the unique identifier of the integration you want to update.

4. Pass the same payload you sent when updating the script, where

   • host is the URL of your Redshift account.

   • database is the name of the existing or new database that the Immuta system user will manage and store metadata in.

   • impersonation specifies whether user impersonation is enabled. See the object description for child parameters.

   • username and password are the credentials for the system account that can act on Redshift objects and configure the integration.

See the config object description for parameter definitions, value types, and additional configuration options.

Response

The response returns the status of the Amazon Redshift Spectrum integration configuration connection. See the response schema reference for details about the response schema.

200 response

A successful response includes the validation tests statuses.

{
  "id": "123456789",
  "status": "editing",
  "validationResults": {
    "status": "passed",
    "validationTests": [
    {
      "name": "Initial Validation: Basic Connection Test",
      "result": [null],
      "status": "passed"
    },
    {
      "name": "Validate Automatic: Immuta Database Does Not Exist",
      "result": [],
      "status": "passed"
    }
    ]
  }
}

Unsuccessful response

Delete an integration

curl -X 'DELETE' \
    'https://www.organization.immuta.com/integrations/{id}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f'

1. Use the script cleanup endpoint (for integrations that were not successfully created) or the delete endpoint (for integrations that were successfully created) to remove Immuta-managed resources from your Amazon Redshift environment.

2. Copy the request example.

3. Replace the Immuta URL and API key with your own.

4. Replace the {id} request parameter with the unique identifier of the integration you want to delete.

Response

The response returns the status of the Amazon Redshift Spectrum integration configuration that has been deleted. See the response schema reference for details about the response schema. An unsuccessful request returns the status code and an error message. See the HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.

{
  "id": "123456789",
  "status": "deleting",
  "validationResults": {
    "status": "passed",
    "validationTests": [
    {
      "name": "Initial Validation: Basic Connection Test",
      "result": [null],
      "status": "passed"
    },
    {
      "name": "Validate Automatic: Immuta Database Does Not Exist",
      "result": [],
      "status": "passed"
    }
    ]
  }
}