Deploy the relay proxy

The Relay Proxy enables your apps to connect directly to Feature Flag services without having to make a significant number of outbound connections to FF services. The Relay Proxy establishes a connection to the Feature Flags configuration data and relays that connection to clients in an organization's network.

This topic describes how to deploy and start the Relay Proxy. For an overview, go to the Relay Proxy Overview.

Requirements

• API key:

  • When the proxy starts up, if an API key does not exist in Feature Flags, the proxy cannot validate that API key during authentication, because the proxy only retrieves API keys at startup and does not check for new ones.
  • If you start the proxy and then later create a new API key in Feature Flags, you must restart the proxy and pass the new API key in its configuration.

• Enable Rosetta 2 for M1 Macs running docker.

• You must set DOCKER_DEFAULT_PLATFORM=linux/amd64

in their environment.

Configure the Relay Proxy

To configure the Relay Proxy:

1. Pull the latest Harness Relay Proxy image from Docker.

   docker pull harness/ff-proxy

2. View all the configuration variables.

   docker run harness/ff-proxy

Details of /app/ff-proxy Configuration variables:

account-identifier string

An account identifier to load remote config.

admin-service string

The URL of the ff admin service (default https://harness.io/gateway/cf).

admin-service-token string

Token to use with the ff service.

api-keys value

API keys to connect with ff-server for each environment.

 auth-secret string

The secret used for signing the authentication token generated by the proxy.

bypass-auth

Bypasses authentication.

client-service string

The URL of the ff client service (default https://config.ff.harness.io/api/1.0).

debug

Enables debug logging.

offline

Enables side loading of data from the config directory.

org-identifier string

An org identifier to load remote config.

port int

Port that the proxy service is exposed on (default 7000).

redis-address string

Redis host:port address.

redis-db int

Database to be selected after connecting to the server.

redis-password string

(Optional) Redis password.

sdk-base-url string

URL for the SDK to connect to (default https://config.ff.harness.io/api/1.0).

sdk-events-url string

URL for the SDK to send metrics to (default https://events.ff.harness.io/api/1.0).

generate-offline-config boolean

 If set to true, the proxy produces an offline configuration in the mounted /config directory, then terminates.

config-dir string

Specifies a path for the offline config directory. The default is /config.

3. Specify your configuration details and Docker run the proxy image.

   The Relay Proxy obtains a list of all Environments and associated API keys for the given Account and Organization when it first starts up, which it will use to validate authentication requests and generate tokens.

   The following are the required configuration variables to connect to the Feature Flags service:

   • admin-service-token: Enter the Service Account details. An auth token that lets the proxy communicate with Feature Flags. For more information on how to create a Service Account, go to Create a Service Account.
   • account-identifier: Enter your account identifier for which you want to retrieve the config. You can copy the account ID from the Harness Manager. In Harness Manager's address bar, copy the Harness account ID from your Harness URL. The Harness account ID comes after account in the URL. For example in the following URL, the account ID is 1a2b3c: https://app.harness.io/#/account/1a2b3c.
   • org-identifier: Enter your organization identifier for which you want to retrieve the config. For more information, go to Create a Harness Organization.
   • api-keys: Enter your server SDK key. For more information, go to Create an SDK key.
   • auth-secret: Enter your authentication secret details. A secret that is used by the proxy to sign the JWTs that it sends to the SDKs. For more information, go to Add a Secrets Manager.

   Examples

   • This is an example of a Docker Relay Proxy image with the required configuration details:

     docker run -d -p 7000:7000 harness/ff-proxy -admin-service-token $MY_SERVICE_TOKEN -account-identifier $MY_ACCOUNT_IDENTIFIER -org-identifier $MY_ORG_IDENTIFIER -api-keys $ENV_1_KEY,$ENV_2_KEY,$ENV_3_KEY... -auth-secret $ANY_AUTH_SECRET

   • This example uses a .env file. Create a .env file with the following environment variables:

     // Create a .env file with these envs   
     DEBUG=false   
     OFFLINE=false   
     PORT=7000   
     ACCOUNT_IDENTIFIER=<string>   
     ORG_IDENTIFIER=<string>   
     ADMIN_SERVICE_TOKEN=<string>   
     AUTH_SECRET=<string>   
     REDIS_ADDRESS=<host:port>   
     API_KEYS=6cfe5e7b-e264-4fa7-b163-befab9fd1223,9e4ec55f-3d11-4621-88c7-5ca0aa8b868b

     Then use the .env file with docker run.

     docker run -d -p 7000:7000 --env-file .env harness/ff-proxy

     For more information, go to Configuration options.

4. (Optional) You can provide config for a Redis instance used to store flag data using the redis-address, redis-db (optional), and redis-password (optional).

   For more information, go to Configure Relay Proxy with Redis below.

   note

   If you do not use Redis, the flag data is stored in the memory. In-memory is the default option.

Configure Relay Proxy with Redis

You can run Redis locally and configure the proxy to work with it. Perform the following steps to configure proxy with Redis.

1. Start Redis.

    docker run --rm --name redis -d -p 6379:6379 redis:latest

2. Start the proxy and configure using a .env.

    docker run -d -p 7000:7000 --env-file .online.uat.env harness/ff-proxy:latest

3. Start the proxy and configure using flags.

   docker run -d -p 7000:7000 harness/ff-proxy -redis-address $REDIS_ADDRESS -admin-service-token $MY_SERVICE_TOKEN -account-identifier $MY_ACCOUNT_IDENTIFIER -org-identifier $MY_ORG_IDENTIFIER -api-keys $ENV_1_KEY,$ENV_2_KEY,$ENV_3_KEY... -auth-secret $ANY_AUTH_SECRET

Configure SDKs to work With the Relay Proxy

The SDKs do not require any additional configuration to work with the proxy. The only difference is that instead of supplying the Feature Flags URL when starting up an SDK, you supply the proxy URL.

For example, if you wanted your SDK to work without the proxy, you'd give it the following URLs (if using the default URLs):

baseURL:   https://config.ff.harness.io/api/1.0

eventsURL: https://events.ff.harness.io/api/1.0

But if you have the proxy running locally on localhost:7000 and it’s connected to Harness, then pass the following URLs to the SDK:

baseURL:   http://localhost:7000

eventsURL: http://localhost:7000

SDK examples with Relay Proxy

The following examples show how to point an SDK at the Relay Proxy:

Go SDK

  
  
go  
proxyURL := "http://localhost:7000"  
apiKey := "your API Key"  
  
target := dto.NewTargetBuilder("your-target").  
    Name("your-target-name").  
    Build()  
  
client, err := harness.NewCfClient(apiKey,  
    harness.WithURL(proxyURL),  
    harness.WithEventsURL(proxyURL),  
    harness.WithTarget(target),  
)  
if err != nil {  
    log.Fatal(err)  
}

.NET SDK

String API_KEY = "YOUR_API_KEY";  
String proxyURL = "http://localhost:7000";  
  
config = Config.Builder()  
                .SetPollingInterval(60000)  
                .SetAnalyticsEnabled()  
                .SetStreamEnabled(true)  
                .EventUrl(proxyURL)  
                .ConfigUrl(proxyURL)  
                .Build();  
  
await CfClient.Instance.Initialize(API_KEY, config);  
  
/**  
 * Define you target on which you would like to evaluate   
 * the featureFlag  
 */  
                Target target =  
                io.harness.cfsdk.client.dto.Target.builder()  
                .Name("User1") //can change with your target name  
                .Identifier("user1@example.com") //can change with your target identifier  
                .build();

JavaScript SDK

javascript  
apiKey = "your API Key"  
proxyURL = "http://localhost:7000"  
  
var cf = initialize(apiKey,  
        {  
            baseUrl: proxyURL,  
            eventUrl: proxyURL,  
        }  
)

Run the Relay Proxy in offline mode

You can configure the Relay Proxy to load and use configuration data that is stored offline. The following configuration data from your Project is stored in a configuration directory:

• Flags
• Targets
• Target Groups
• Hashed data of your SDK keys

This stored configuration is then loaded from this directory when you enable the offline Flag.

To use offline mode:

1. Generate the offline configuration directory
2. Run the proxy in offline mode when needed

Generate the offline configuration directory

You need to generate the configuration directory that contains your Project data before you can run the proxy in offline mode. To do this you run the proxy using your usual configuration, but also:

1. Include the variable for generating an offline configuration.
2. Mount your configuration directory to the docker container.

How you add these depends on whether you use Flags or a .env file:

Docker command when using flags

As well as your usual variables, include the generate-offline-config variable and add the directory path in place of {YOUR_ABSOLUTE_PATH}:

docker run -d -p 7000:7000 -v {YOUR_ABSOLUTE_PATH}/config:/config ff-proxy -generate-offline-config -admin-service-token $MY_SERVICE_TOKEN -account-identifier $MY_ACCOUNT_IDENTIFIER -org-identifier $MY_ORG_IDENTIFIER -api-keys $ENV_1_KEY,$ENV_2_KEY,$ENV_3_KEY... -auth-secret $ANY_AUTH_SECRET

Docker command when using a .env file

Add GENERATE_OFFLINE_CONFIG=true to your .env file, and add the directory path in place of {YOUR_ABSOLUTE_PATH}:

docker run -d -p 7000:7000 --env-file .env -v {YOUR_ABSOULUTE_PATH}/config:/config ff-proxy

This generates the configuration you need to run the proxy in offline mode, then terminates. To then use the offline configuration you store, you need to run the proxy in offline mode.

Run the proxy in offline mode when needed

After you have generated a configuration directory, you can load the data from it any time you need to run the proxy offline. To use the stored configuration when the proxy is offline you run the proxy using your usual configuration, but also:

1. Include the variable for running offline.
2. Mount your configuration directory to the docker container.

When you run the proxy in offline mode, it remains offline until you run the proxy in online mode again. This means that the proxy won't send metrics data or connect to the Harness servers.How you run the proxy in offline mode depends on whether you use flags or a .env file:

Docker command when using flags

Run the following Docker command and add the directory path in place of {YOUR_ABSOLUTE_PATH}as well as your usual variables:

docker run -d -p 7000:7000 -v {YOUR_ABSOULUTE_PATH}/config:/config ff-proxy -offline -admin-service-token $MY_SERVICE_TOKEN -account-identifier $MY_ACCOUNT_IDENTIFIER -org-identifier $MY_ORG_IDENTIFIER -api-keys $ENV_1_KEY,$ENV_2_KEY,$ENV_3_KEY... -auth-secret $ANY_AUTH_SECRET

Docker command when using a .env file

Add OFFLINE=true to your .env file and add the directory path in place of {YOUR_ABSOLUTE_PATH}:

docker run -d -p 7000:7000 --env-file .env -v {YOUR_ABSOULUTE_PATH}/config:/config ff-proxy

## More information

For more information