Deploy Relay Proxy

Updated 1 week ago by Archana Singh

Currently, this feature is in Beta. Once the feature is released to a general audience, it will be available for all Harness accounts.

This topic describes how to deploy and start the Relay Proxy.

In this topic:

Before You Begin

Limitations

  • When the Proxy starts up, if an API key does not exist in Feature Flags, the Proxy will not be able to 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.

Configure Relay Proxy

You can start the Relay Proxy by pulling the harness/ff-proxy image from Docker.

  1. Pull the latest Relay Proxy Docker image.

    docker pull harness/ff-proxy
  2. View the configuration variables by running the following command:

    docker run harness/ff-proxy

    This prints all the configuration variables.
    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 auth tokens

    bypass-auth

    Bypasses authentication

    client-service string

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

    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/)

    sdk-events-url string

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


    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, see 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 1a2b3chttps://app.harness.io/#/account/1a2b3c.
    • org-identifier: Enter your organization identifier for which you want to retrieve the config. For more information, see Create a Harness Organization.
    • api-keys: Enter your API keys. A list of API keys that you want the proxy to be enabled to work with. For more information, see Add and Manage API Keys.
    • 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, see Add a Secrets Manager.
  3. Specify your configuration details and Docker run the proxy image. The following are the examples:
    1. Here 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
    2. The following 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>

      Then use the .env file with docker run

      docker run -d -p 7000:7000 --env-file .env harness/ff-proxy
  4. (Optional) You can optionally provide config for a Redis instance used to store flag data using the redis-address, redis-db (optional), and redis-password (optional).
    If you do not use Redis, the flag data is stored in the memory. In-memory is the default option.

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 should pass the proxy URL.

For example, if you wanted your SDK to go via QA without the Proxy, you'd give it the following URLs:

baseURL:   http://config.feature-flags.qa.harness.io/api/1.0

eventsURL: http://event.feature-flags.qa.harness.io/api/1.0

But if you have a Proxy running locally on localhost:7000 and it’s connected to QA 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: apiKey,
eventUrl: apiKey,
}
)


Please Provide Feedback