Redshift native Experimentation

This topic explains how to set up the Redshift warehouse native Experimentation integration. Redshift native Experimentation enables you to run experiments in LaunchDarkly using data directly from your Amazon Redshift data warehouse. This lets LaunchDarkly experiments read and analyze your metrics data stored in Redshift, without requiring you to send event data through LaunchDarkly SDKs. The integration uses the same Redshift cluster and AWS account as the Redshift Data Export destination for the project and environment you select. LaunchDarkly reads exported events from that destination and writes computed experiment results to an Experimentation database on the same cluster. Setting up the integration requires the following steps:

1. Gathering your Redshift cluster information
2. Configuring the LaunchDarkly integration
3. Creating AWS resources
4. Configuring network access
5. Verifying the connection

​

Prerequisites

Before setting up Redshift native Experimentation, ensure that you have:

• The Redshift Data Export integration set up in LaunchDarkly.
• Administrative access to your AWS account with permissions to create AWS Identity and Access Management (IAM) policies and roles
• An active Amazon Redshift cluster
• A LaunchDarkly role of Owner or Admin, or a custom role that allows the following actions:
  • add and edit integrations
  • add destinations
  • add metric data sources
• Metric event data in your Redshift database that you want to use for Experimentation

​

Step 1: Gather your Redshift cluster information

LaunchDarkly fills most cluster details from your Redshift Data Export destination. Collect the values LaunchDarkly cannot fill, and the location of your metric event data:

• The name of the database that contains your metric event data.
• The name of the schema that contains your metric event tables, if you want to limit read access to one schema.
• The cluster region, such as us-east-1, when LaunchDarkly does not fill Cluster region.
• Your 12-digit AWS account ID, when LaunchDarkly does not fill AWS account ID.

LaunchDarkly fills Cluster endpoint and Cluster identifier from the Data Export destination. It fills Cluster region when it can read the region from that endpoint, and AWS account ID when the Data Export destination stores an IAM role Amazon Resource Name (ARN). You can confirm the cluster identifier and region on the cluster’s “General information” screen:

​

Step 2: Configure the LaunchDarkly integration

This step records where your metric data lives, generates the IAM policies and SQL scripts, and saves the integration after LaunchDarkly verifies the connection. This integration is separate from the Redshift Data Export integration. To set up the integration:

1. Navigate to the Integrations page.
2. Search for and select Redshift Native Experimentation.
3. Click Add integration.
4. Enter an integration Name.
5. Select the LaunchDarkly project and environment. Only environments that already have a Redshift Data Export destination are available. You cannot change the project or environment after you save.
6. Confirm the fields under “Step 1. Configure your Redshift cluster.” LaunchDarkly fills Cluster endpoint and Cluster identifier from the Data Export destination. You cannot edit those two fields. Cluster region and AWS account ID stay editable only when LaunchDarkly cannot derive them. The integration must use the same cluster and AWS account as that destination.

7. Under “Step 2. Configure resource names,” enter the Metrics database name. This is the database that contains your metric event data. LaunchDarkly is granted read access to this database.
8. (Optional) Enter the Metrics schema name. Leave it blank to grant read access to every schema in the metrics database.
9. (Optional) Expand Additional fields (optional) to rename the database, schema, permission groups, and service users that LaunchDarkly creates. Leave a field blank to keep its default name. To learn more, read Choosing custom object names.
10. Under “Step 3. Generate policies and scripts,” click Generate policies and scripts. LaunchDarkly displays an IAM permissions policy, an IAM trust policy, and four SQL scripts. Copy and save them for the next section.
11. Create the IAM policy and role, then run the SQL scripts. To learn more, read Step 3: Create AWS resources.
12. Return to the configuration page. Under “Step 4. Set up AWS IAM access,” paste the role ARN into IAM role ARN.
13. Select the “I have read and agree to the Integration Terms and Conditions” checkbox.
14. Click Test connection and save.

After you generate the policies and scripts, LaunchDarkly saves a draft. You can leave the page and open the draft again from the integrations list. The project and environment stay locked on the draft. If you change the cluster details, the metrics database, or the metrics schema, click Generate policies and scripts again before you save. Changing the integration Name does not clear the generated policies and scripts.

​

Choose custom object names

Additional fields (optional) renames the objects the setup scripts create. Leave a field blank to use the default name. For a project key my-project and an environment key staging, the default names are:

• Experimentation database name: The database LaunchDarkly creates and connects to. Defaults to ld_experimentation.
• Experimentation group name: The permission group LaunchDarkly uses to write experiment results. Defaults to ld_experimentation_role.
• Data source group name: The permission group LaunchDarkly uses to read your metrics. Defaults to ld_data_source_role.
• Experimentation user name: The service user LaunchDarkly authenticates as to write experiment results. Defaults to ld_experimentation_user_my_project__staging.
• Data source user name: The service user LaunchDarkly authenticates as to read your metrics. Defaults to ld_data_source_user_my_project__staging.
• Results schema name: The schema, inside the experimentation database, where LaunchDarkly writes computed experiment results. Defaults to results_my_project__staging.

LaunchDarkly builds the user and schema defaults from your project key and environment key. It lowercases each key and replaces characters other than letters and digits with underscores, then joins the two keys with __. A custom name must meet all of the following rules:

• Use lowercase letters, digits, and underscores.
• Start with a letter or an underscore.
• Use 127 characters or fewer.
• Do not use a Redshift reserved word, such as user, group, or table.
• Use a different name for each permission group, and a different name for each service user.

LaunchDarkly also checks names against other configurations on the same cluster. The comparison ignores letter case. Permission groups, the metrics database, and the metrics schema can be shared. LaunchDarkly rejects the configuration in these cases:

• A service user name matches a service user on another Redshift native Experimentation integration on the same cluster.
• A service user name matches the user on a Redshift Data Export destination on the same cluster.
• The experimentation database is the database a Redshift Data Export destination uses on the same cluster, including the default database ld_export.
• Two integrations on the same cluster would write results to the same schema in the same experimentation database. They can share an experimentation database when each integration uses a different results schema.

LaunchDarkly checks these rules when you generate the policies and scripts, and again when you save. A draft does not reserve the names. You cannot change the names after you save. To use different names, delete the integration and create a new one.

​

Step 3: Create AWS resources

Use the IAM policies and SQL scripts from the configuration page to create the required resources in your AWS account.

​

Create the IAM policy

To create the IAM policy:

1. Navigate to IAM > Policies in the AWS console.
2. Click Create policy.
3. Select the JSON tab.
4. Paste the IAM permissions policy you copied from LaunchDarkly.
5. Click Next.
6. Enter a policy name, such as LaunchDarklyRedshiftAccess.
7. Click Create policy.

​

Create the IAM role

To create the IAM role:

1. Navigate to IAM > Roles in the AWS console.
2. Click Create role.
3. Select Custom trust policy.
4. Paste the IAM trust policy you copied from LaunchDarkly.

5. Click Next.
6. Search for and select the policy you created in the previous section, such as LaunchDarklyRedshiftAccess.
7. Click Next.
8. Provide a role name, such as LaunchDarklyRedshiftRole.
9. Click Create role.
10. Copy the Role ARN from the role summary page.
11. Return to the LaunchDarkly configuration page and paste the role ARN into IAM role ARN.

​

Run the SQL setup scripts

Run the four SQL scripts in order. Each script is labeled on the configuration page:

1. “Create the experimentation database, groups, and users”
2. “Grant access to the results schema”
3. “Grant access to the Data Export schema”
4. “Grant LaunchDarkly read access to your metrics”

Follow AWS’s instructions to connect to your Redshift cluster using your preferred SQL client. Paste and run each script. The scripts include comments that describe each statement. The third script grants the experimentation permission group access to the schema where Redshift Data Export writes events. It uses the database, schema, and user from that Data Export destination, including any names you set when you configured Data Export.

​

Step 4: Configure network access

Configure your Redshift cluster to accept connections from the following LaunchDarkly IP addresses:

1. Navigate to your Redshift cluster in the AWS console.
2. Go to Properties > Network and security.
3. Edit the VPC security group.
4. Add inbound rules for each of the following IPs. Set the Type to “Custom TCP” and the Port to “5439”:

​

Step 5: Verify the connection

Test connection and save checks that LaunchDarkly can connect to the cluster and that the experimentation permission group can use the Data Export schema. If the check fails, LaunchDarkly does not activate the integration. The draft remains, which means you can correct the setup and try again. If you just created the IAM role, wait a minute for the role to propagate, then click Test connection and save again. After LaunchDarkly activates the integration, the configuration page shows “Connection status.” A green Healthy status confirms LaunchDarkly can connect to Redshift and has the correct permissions. If you encounter issues with your setup, you can take the following actions:

• Check the integration status in LaunchDarkly for error messages
• Review your AWS CloudTrail logs for IAM role assumption attempts
• Check your Redshift system tables for connection and query logs

If you are still having trouble with your connection contact LaunchDarkly Support with the following information:

• Your integration configuration ID
• Any error messages from the connection status
• Your AWS CloudTrail logs, if available
• Your Redshift cluster configuration details, including endpoint, region, and version

​

Edit a saved integration

After LaunchDarkly saves the integration, you can change the integration Name and the Maintainer. You cannot change the project, environment, cluster details, metrics database, metrics schema, custom object names, or IAM role ARN. The configuration page shows the SQL scripts that granted LaunchDarkly access. The scripts are read-only. If LaunchDarkly cannot load them, “Step 3. Generate policies and scripts” stays on the page with a warning. Click Refresh to try again.

​

Next steps

Read the following topics to understand how to create a Redshift native experiment and analyze the experiment results:

• Creating experiments using warehouse native metrics
• Analyzing experiments

The results page for a warehouse native experiment displays the date and time the results were last updated from Redshift. The initial load of experiment results can take up to 60 minutes to appear, and further results updates appear within 15–30 minutes.