Automatic configuration

Overview

This topic explains how to set up the Relay Proxy's automatic configuration feature.

With automatic configuration, the Relay Proxy automatically detects and supports new connections to updated or new environments whenever changes occur that impact LaunchDarkly SDK keys, mobile keys, or client-side IDs.

Benefits of automatic configuration

In a standard Relay Proxy, without automatic configuration, whenever you add or make changes to environments and projects in LaunchDarkly, you must manually update configuration files and restart the Relay Proxy to reflect the changes.

With automatic configuration enabled, you no longer need to manually update the Relay Proxy's configuration files after you make configuration changes, nor do you need to restart the Relay Proxy for changes to take effect.

Additionally, you can use a page in the LaunchDarkly user interface (UI) to configure your Relay Proxy with the automatic configuration feature. A standard Relay Proxy requires all environments to be defined individually, and you cannot configure it through the LaunchDarkly UI.

If you enable automatic configuration, your Relay Proxy automatically detects and reacts to server-sent events including the following:

• SDK key rotation
• Mobile key rotation
• Environment state changes, such as new environment creation, name and tag updates, and environment deletion
• Project state changes, such as new project creation, name and tag updates, and project deletion

This prevents you from needing to restart your Relay Proxy instances and potentially cause downtime while applying changes. These changes have no impact on your Relay Proxy's performance.

With automatic configuration enabled, you only need to restart the Relay Proxy to upgrade it.

Enable automatic configuration

To enable automatic configuration, you must be a LaunchDarkly Owner or Admin, or have a custom role that allows the createRelayAutoConfiguration action. To learn more, read Relay Proxy configuration actions.

Enabling automatic configuration is a two-step process. These steps appear in detail below.

You must:

1. Create a Relay Proxy configuration on the Relay Proxy page under Organization settings and save its unique key.
2. Configure your Relay Proxy instance to use the unique key from the prior step. You may do so either as a property in your Relay Proxy configuration file or as an environment variable.

Here's how to create a Relay Proxy configuration in the LaunchDarkly UI:

1. Click the gear icon in the left sidenav to view Organization settings.
2. Click Relay proxy. The "Relay Proxy" page opens.
3. Click Create configuration. The "Create a Relay Proxy configuration" panel appears.
4. Give the Relay Proxy a human-readable Name.
5. Choose a Rule from the menu. This rule determines what content the Relay Proxy receives.

• "All projects and environments" sends changes about all projects and environments to the Relay Proxy.
• "Inline policy" allows you to specify which projects and environments you can track events for. To learn more, read Write an inline policy.

6. Click Save configuration. The Relay Proxy appears on the Relay Proxy page with its key visible.
7. Copy and save the key somewhere secure:

Next you must specify the key in a Relay Proxy configuration file so it includes the configuration you created. Here's how:

1. Configure your Relay Proxy to use your new key.

• If you configured the Relay Proxy with a configuration file, specify the Relay Proxy key in an AutoConfig section as the key property.

• If you configured the Relay Proxy with environment variables, specify the Relay Proxy key with the AUTO_CONFIG_KEY environment variable. Here's how:

  Configuration file

  Environment variables

  [AutoConfig]
  key = "rel-EXAMPLE-RELAY-PROXY-CONFIGURATION-KEY"
  COPY

2. Start the Relay Proxy.

From now on, the Relay Proxy will respond automatically to the project and environment state changes you specified.

Write an inline policy

You can use the inline policy editor to specify precise instructions on what environments and projects the Relay Proxy should include or exclude. You can write policies by hand to get exactly the outcomes you want.

There are three ways to write an inline policy:

• Using the simple editor
• Using the resource finder
• Using the advanced editor

Each of these methods is described below.

Expand Using the simple editor

Use the simple editor

You can create simple, one-line policies using the simple editor. To learn more about policy syntax, read Resource specifiers.

To use the simple editor from the "Create a Relay Proxy configuration" panel:

1. Choose "inline policy" from the Rule menu.
2. Enter a policy in the "Choose resources for this policy statement" field. In this example, proj/default:env/* gives the Relay Proxy access to all environments within the default project.

5. Click Save configuration.

Expand Using the resource finder

Use the resource finder

To create an inline policy using the resource finder from the "Create a Relay Proxy configuration" panel:

1. Choose "inline policy" from the Rule menu.
2. Click Resource finder. A "Find a resource" dialog appears.

3. Search for the resource you want the Relay Proxy to have access to.
4. Select the resource. The resource appears in the Choose resources for this policy statement field.
5. Click Save configuration.

Expand Using the advanced editor

Use the advanced editor

To write more complicated policies you can use the advanced editor. To learn how to write advanced policies, read About policies.

To use the advanced editor from the "Create a Relay Proxy configuration" panel:

1. Choose "inline policy" from the Rule menu.
2. Click Advanced editor. The advanced editor window appears.
3. Enter your policy.
4. Click Save configuration.

Example access policies

You can limit the environments to include in an automatic Relay Proxy configuration. Expand each section below to view custom role policy examples.

[
  {
    "actions": ["*" ],
    "effect": "allow",
    "resources": ["proj/*:env/production" ]
  }
]
COPY

[
  {
    "actions": ["*"],
    "effect": "allow",
    "resources": ["proj/mobile:env/production" ]
  }
]
COPY

[
  {
    "actions": ["*"],
    "effect": "allow",
    "resources": ["proj/mobile-*:env/*" ]
  }
]
COPY

[
  {
    "actions": ["*"],
    "effect": "allow",
    "resources": ["proj/*;mobile:env/production" ]
  }
]
COPY

[
  {
    "actions": ["*" ],
    "effect": "allow",
    "resources": ["proj/*:env/*"]
  },
  {
    "actions": ["*"],
    "effect": "deny",
    "resources": [
      "proj/*:env/production",
      "proj/*;federal:env/*"
    ]
  }
]
COPY

Write a custom role with access to the Relay Proxy

You can give members access to the Relay Proxy using the relay-proxy-config resource in a custom role policy. To learn more about Relay Proxy resource actions, read Relay Proxy configuration actions.

You can copy and paste this custom role policy into the advanced editor to grant access to all Relay Proxy actions:

[
  {
    "effect": "allow",
    "actions": ["*"],
    "resources": ["relay-proxy-config"]
  }
]
COPY

To learn more about creating custom roles, read Custom roles.