IOptions | etcd3

IOptions are passed into the client constructor to configure how the client connects to etcd. It supports defining multiple servers and configuring how load is balanced between those servers.

Hierarchy

IOptions

Index

Properties

Optional auth

auth: undefined | { callOptions?: CallOptionsFactory; password: string; username: string }

Etcd password auth, if using. You can also specify call options for the authentication token exchange call.

Optional credentials

credentials: undefined | { certChain?: Buffer; privateKey?: Buffer; rootCertificate: Buffer }

Optional client cert credentials for talking to etcd. Describe more here, passed into the createSsl function in GRPC here.

For example:

const etcd = new Etcd3({
  credentials: {
    rootCertificate: fs.readFileSync('ca.crt'),
  },
});

Optional defaultCallOptions

defaultCallOptions: CallOptionsFactory

Default call options used for all requests. This can be an object, or a function which will be called for each etcd method call. As a function, it will be called with a context object, which looks like:

{
  service: 'KV',   // etcd service name
  method: 'range', // etcd method name
  isStream: false, // whether the call create a stream
  params: { ... }, // arguments given to the call
}

For example, this will set a 10 second timeout on all calls which are not streams:

const etcd3 = new Etcd3({
  defaultCallOptions: context => context.isStream ? {} : { deadline: Date.now() + 10000 },
});

The default options are shallow merged with any call-specific options. For example this will always result in a 5 second timeout, regardless of what the defaultCallOptions contains:

etcd3.get('foo').options({ deadline: Date.now() + 5000 })

Optional dialTimeout

dialTimeout: undefined | number

Duration in milliseconds to wait while connecting before timing out. Defaults to 30 seconds.

Optional faultHandling

faultHandling: Partial<{ global: IPolicy<IDefaultPolicyContext>; host: (hostname: string) => IPolicy<IDefaultPolicyContext>; watchBackoff: IBackoff<unknown> }>

Defines the fault-handling policies for the client via Cockatiel. There are two policies: per-host, and global. Calls will call through the global policy, and then to a host policy. Each time the global policy retries, it will pick a new host to run the call on.

The recommended setup for this is to put a retry policy on the global slot, and a circuit-breaker policy guarding each host. Additionally, you can configure a backoff that the watch manager will use for reconnecting watch streams.

By default, global is set to a three-retry policy and host is a circuit breaker that will open (stop sending requests) for five seconds after three consecutive failures. The watch backoff defaults to Cockatiel's default exponential options (a max 30 second delay on a decorrelated jitter).

For example, this is how you would manually specify the default options:

import { Etcd3, isRecoverableError } from 'etcd3';
import { Policy, ConsecutiveBreaker, ExponentialBackoff } from 'cockatiel';

const etcd = new Etcd3({
  faultHandling: {
    host: () =>
      Policy.handleWhen(isRecoverableError).circuitBreaker(5_000, new ConsecutiveBreaker(3)),
    global: Policy.handleWhen(isRecoverableError).retry(3),
    watchBackoff: new ExponentialBackoff(),
  },
});

Here's how you can disable all fault-handling logic:

import { Etcd3 } from 'etcd3';
import { Policy } from 'cockatiel';

const etcd = new Etcd3({
  faultHandling: {
    host: () => Policy.noop,
    global: Policy.noop,
  },
});

Optional grpcOptions

grpcOptions: ChannelOptions

Internal options to configure the GRPC client. These are channel options as enumerated in their C++ documentation. For example:

const etcd = new Etcd3({
  // ...
  grpcOptions: {
    'grpc.http2.max_ping_strikes': 3,
  },
})

hosts

hosts: string[] | string

A list of hosts to connect to. Hosts should include the https?:// prefix.

Generated using TypeDoc