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 an inline policy to specify precise instructions on what environments and projects the Relay Proxy should include or exclude. An inline policy is similar to a custom role, but is created as part of the Relay Proxy configuration.

There are two ways to write an inline policy:

• Using the policy builder
• Using the advanced editor

Each of these methods is described below.

Expand Using the policy builder

Use the policy builder

You can create most policies using the policy builder.

To use the policy builder from the "Create a Relay Proxy configuration" panel:

1. Choose "inline policy" from the Rule menu.
2. Click + Add statement.
3. Use the Scope menu to specify the resources this policy affects.

• Select the resource type.
• In the Select an operation menu, select whether the scope of the statement should be all resources of this type, all resources except for a select few, or only a select few.
• If necessary, choose these select few from the Select [resources] menu.

4. Use the Actions menu to specify whether to allow or deny actions on these resources.
5. Click Save configuration.

This example gives the Relay Proxy access to all environments within the default project:

To learn more about using the policy builder, read Create policies for custom roles.

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 View JSON. 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.