Home

Awesome

中文

[TOC]

Introduction

Etcd is a highly available key-value storage system for shared configuration and service discovery. It is developed by CoreOS for distributed system configuration management and service discovery. To facilitate users to connect to the Etcd system, we provide the Etcd data source plugin, which allows users to easily load configuration data from etcd clusters and use this data in their programs.

Usage

For detailed usage examples, please refer to: Etcd examples

Dependency

Bazel

  1. Import the repository

    In the WORKSPACE file of the project, import the cpp-config-etcd repository and its dependencies:

    load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository")
    
    git_repository(
        name = "trpc_cpp",
        remote = "https://github.com/trpc-group/trpc-cpp.git",
        branch = "main",
    )
    
    load("@trpc_cpp//trpc:workspace.bzl", "trpc_workspace")
    trpc_workspace()
    
    git_repository(
        name = "cpp-config-etcd",
        remote = "https://github.com/trpc-ecosystem/cpp-config-etcd.git",
        branch = "main",
    )
    
    load("@etcd-provider//trpc:workspace.bzl", "config_etcd_workspace")
    config_etcd_workspace()
    

    etcd-client-cpp relies on many third-party libraries, and bazel compilation based solely on source code is troublesome. In order to simplify the compilation process, we introduce etcd-client-cpp and its necessary dependent libraries grpc, rest and so on through the way of local libraries. Before compiling, you need to install etcd-client-cpp and related dependencies in /usr/local.

  2. Import the plugin

    In the target that needs to use Etcd, introduce the "trpc/config/etcd:etcd_provider_api" dependency. For example:

    cc_binary(
       name = "helloworld_server",
       srcs = ["helloworld_server.cc"],
       deps = [
           "@cpp-config-etcd//trpc/config/etcd:etcd_provider",
           ...
       ],
    )
    

Cmake

Not supported yet.

Plugin Configuration

To use the Etcd plugin, you must add the plugin configuration in the framework configuration file:

plugins:
   config:
      etcd:
         providers:
            - name: etcd1
              endpoint: "http://127.0.0.1:2379"
              prefix: ""

The following is a detailed explanation of these configuration items:

配置项类型默认值说明
namestringNo default value, must be setThe name of the etcd provider, used in the code to specify which etcd provider to use through the ::trpc::config::WithProvider function
endpointstringNo default value, must be setThe access address of the etcd cluster, in the format "http://ip:port"
prefixstringEmpty string (optional configuration)The prefix of the key that stores configuration data in etcd, used to distinguish different configuration data

Initialization

The etcd-provider plugin provides the plugin registration interface ::trpc::config::etcd::Init(), which users need to call before the framework starts.

For the server scenario, the user needs to call it in the TrpcApp::RegisterPlugins function when the service starts:

```cpp
#include "trpc/config/etcd/etcd_provider_api.h"

class HelloworldServer : public ::trpc::TrpcApp {
 public:
  ...
  int RegisterPlugins() override {
    ::trpc::config::etcd::Init();
    return 0;
  }
};
```

2. For the pure client scenario, it needs to be called after the framework configuration is started and before the other modules of the framework are started:

```cpp
#include "trpc/config/etcd/etcd_provider_api.h"

int main(int argc, char* argv[]) {
  ParseClientConfig(argc, argv);

  ::trpc::config::etcd::Init();

  return ::trpc::RunInTrpcRuntime([]() { return Run(); });
}
```

Precautions

Install etcd cluster

  1. Visit the official etcd GitHub repository, on the page, you can find detailed guidance on installing and deploying an etcd cluster. You can select an installation method based on your operating system and environment.

  2. For simple testing and development purposes, you can run a single-node etcd cluster locally. Please refer to the "Getting Started" section in the etcd official documentation to learn how to start an etcd instance locally.

  3. For production environments, it is recommended to deploy a multi-node etcd cluster to ensure high availability and data consistency. Please refer to the "Runtime Configuration" section in the etcd official documentation to learn how to configure and deploy a multi-node etcd cluster.

Use etcdctl tool to set key-value pairs