• Home
  • Integrations
  • SDKs
  • Guides
  • API docs
    No results for ""
    EXPAND ALL

    EDIT ON GITHUB

    Consul

    Read time: 2 minutes
    Last edited: Oct 24, 2022

    Overview

    This topic explains how to use the SDK Consul integration as a persistent feature store.

    Data size limit in Consul

    Consul does not support storing values greater than 512KB. Using Consul as a persistent feature store does not work if the JSON representation of any feature flag or user segment exceeds that size. To learn more about these limitations, read Consul's documentation.

    To view the JSON representations of all flags and segments, query https://sdk.launchdarkly.com/sdk/latest-all with your SDK key in the Authorization header.

    How the SDKs store data in Consul

    The Consul integrations for all LaunchDarkly server-side SDKs use the same conventions, so that SDK instances and Relay Proxy instances sharing a single Consul store can interoperate correctly.

    The storage schema is as follows:

    • There is always a "prefix" string that provides a namespace for the overall data set. If you do not specify a prefix in your configuration, it is launchdarkly.
    • For each data item that the SDK can store, such as a feature flag, there is a Consul key-value pair where the key is PREFIX/TYPE/KEY. PREFIX is the configured prefix string. TYPE denotes the type of data such as features and segments. KEY is the unique key of the item. For example, a KEY could be the flag key for a feature flag. The value is a serialized representation of that item, in a format that is determined by the SDK.
    • An additional key, PREFIX/$inited, is created with an arbitrary value when the SDK stores a full set of feature flag data. This allows a new SDK instance to check whether there is already a valid data set that was stored earlier.
    • The SDK may use additional keys starting with the PREFIX string, so you should not assume that the TYPE values mentioned above and $inited are the only possible keys. But the SDK never adds, modifies, or removes any keys in Consul other than ones starting with the PREFIX, so it is safe to share a Consul instance that is also being used for other purposes.

    Server-side SDKs

    In the following examples, the Consul feature store is set to use a host address of my-consul:8100, a prefix string of "my-key-prefix", and a cache TTL of 30 seconds.

    This feature is available in the following server-side SDKs:

    .NET (server-side)

    Expand .NET (server-side) code sample

    If using the .NET SDK, you must install the additional package LaunchDarkly.ServerSdk.Consul.

    using LaunchDarkly.Sdk.Server;
    using LaunchDarkly.Sdk.Server.Integrations;
    var config = Configuration.Builder(sdkKey)
    .DataStore(
    Components.PersistentDataStore(
    Consul.DataStore().Address("http://my-consul:8100")
    ).CacheSeconds(30)
    )
    .Build();
    var client = new LDClient(config);
    // Before version 6.0, the syntax was different:
    using LaunchDarkly.Client;
    using LaunchDarkly.Client.Consul;
    var store = ConsulComponents.ConsulFeatureStore()
    .WithAddress(new Uri("http://my-consul:8100"))
    .WithCaching(FeatureStoreCacheConfig.Enabled.WithTtlSeconds(30));
    var config = Configuration.Default(sdkKey)
    .WithFeatureStoreFactory(store);
    var client = new LDClient(config);

    To learn more, read dotnet-server-sdk-consul.

    Go

    Expand Go code sample

    The Go integration is in github.com/launchdarkly/go-server-sdk-consul for version 5.0.0 or higher of the SDK. In versions 4.5.0 and higher, but below 5.0.0, it is in the main SDK distribution as the subpackage ldconsul.

    import (
    ld "gopkg.in/launchdarkly/go-server-sdk.v5"
    "gopkg.in/launchdarkly/go-server-sdk.v5/ldcomponents"
    ldconsul "github.com/launchdarkly/go-server-sdk-consul"
    )
    var config ld.Config
    config.DataStore = ldcomponents.PersistentDataStore(
    ldconsul.DataStore().
    Address("http://my-consul:8100").
    Prefix("my-key-prefix"),
    ).CacheSeconds(30)
    client := ld.MakeCustomClient(sdkKey, config, waitTime)

    To learn more, read go-server-sdk-consul.

    Java

    Expand Java code sample

    If using the Java SDK, you must install the additional package com.launchdarkly.launchdarkly-java-server-sdk-consul-store.

    import com.launchdarkly.sdk.server.*;
    import com.launchdarkly.sdk.server.integrations.*;
    LDConfig config = new LDConfig.Builder()
    .dataStore(
    Components.persistentDataStore(
    Consul.dataStore().url(URL.create("http://my-consul:8100"))
    .prefix("my-key-prefix")
    ).cacheSeconds(30)
    )
    .build();
    LDClient client = new LDClient(sdkKey, config);

    To learn more, read java-server-sdk-consul.

    Node.js (server-side)

    Expand Node.js (server-side) code sample

    If using the Node.js SDK you must install the additional package launchdarkly-node-server-consul.

    const ld = require('launchdarkly-node-server-sdk');
    const ConsulFeatureStore = require('launchdarkly-node-server-sdk-consul');
    const store = ConsulFeatureStore({
    consulOptions: {
    host: 'your-consul',
    port: 8100
    },
    prefix: 'your-key-prefix',
    cacheTTL: 30
    });
    const options = {
    featureStore: store
    };
    const client = ld.init('YOUR_SDK_KEY', options);

    PHP

    Expand PHP code sample

    In version 4.0 and higher of the PHP SDK, you must add the package launchdarkly/server-sdk-consul to your application's Composer dependencies to use the Consul integration.

    In versions 3.x and earlier, the Consul integration is built into the main SDK package, but you must add a package dependency for aws/sensiolabs/consul-php-sdk.

    To use the Consul integration:

    $fr = LaunchDarkly\Integrations\Consul::featureRequester([
    'consul_uri' => 'http://my-consul:8100',
    'consul_prefix' => 'my-key-prefix'
    ]);
    $client = new LaunchDarkly\LDClient("your_sdk_key", [
    'feature_requester' => $fr
    ]);

    To learn more, read php-server-sdk-consul.

    Python

    Expand Python code sample

    The Python integration is part of the main SDK distribution as of version 6.8.1, but you must also install the package python-consul. Python 3.3 and 3.4 are not supported.

    import ldclient
    from ldclient.config import Config
    from ldclient.feature_store import CacheConfig
    from ldclient.integrations import Consul
    store = Consul.new_feature_store(host='my-consul', port=8100,
    prefix='my-key-prefix', caching=CacheConfig(expiration=30))
    config = Config(feature_store=store)
    ldclient.set_config(config)

    Ruby

    Expand Ruby code sample

    The Ruby integration is part of the main SDK distribution as of version 5.1.1, but you must also install the gem diplomat.

    require 'ldclient-rb'
    store = LaunchDarkly::Integrations::Consul.new_feature_store(
    { url: 'http://my-consul:8100', prefix: 'my-key-prefix', expiration: 30 })
    config = LaunchDarkly::Config.new(
    feature_store: store
    )
    client = LaunchDarkly::Client.new(sdk_key, config)