EtcdConfiguration with information about an endpoint to which requests will be sent and optional authorization data.
Adds a member to an etcd cluster.
Adds a member to an etcd cluster.
Implemented according to etcd Members API: "Add a member".
EtcdMemberForm containing a list of strings representing the peer URLs of the new member.
A Future wrapped around either EtcdAddMemberResponse or EtcdStandardError extending EtcdAddMemberResult.
Adds new roles and modifies role details.
Adds new roles and modifies role details.
Implemented according to etcd Auth and Security API: "API endpoints".
EtcdRole with details of the role to be created or updated.
A Future wrapped around either EtcdAddUpdateRoleResponse or EtcdStandardError. extending EtcdAddUpdateRoleResult.
Adds new users and modifies user details.
Adds new users and modifies user details.
Implemented according to etcd Auth and Security API: "API endpoints".
EtcdUserRequestForm containing the details (login, password, granted and revoked permissions, and roles) to be updated for a given user.
A Future wrapped around either EtcdAddUpdateUserResponse or EtcdStandardError. extending EtcdAddUpdateUserResult.
Changes the peer urls of a member of an etcd cluster.
Changes the peer urls of a member of an etcd cluster.
Implemented according to etcd Members API: "Change the peer urls of a member".
A string identifying another member of the etcd cluster.
EtcdMemberForm containing a list of strings representing the new peer URLs that will replace the old ones.
A Future wrapped around either EtcdConfirmationResponse or EtcdStandardError extending EtcdConfirmationResult.
Close the internal resources.
Creates an empty directory in the specified path.
Creates an empty directory in the specified path.
Implemented according to etcd Client API: "Creating Directories". See also "Using a directory TTL".
One can also choose to create a directory by setting a key in it using EtcdClient.setKey.
Optionally one can choose a TTL (time to live), which is a lifespan in seconds for the directory. When it expires, the directory is deleted. To update the TTL, use method EtcdClient.refreshDirTTL.
EtcdDirectory to be created.
Life span in seconds of the directory. Defaults to None.
A Future wrapped around either EtcdCreateDirResponse or EtcdRequestError extending EtcdCreateDirResult.
Creates a key in a specified directory whose name is the current etcd index preceded with leading zeroes.
Creates a key in a specified directory whose name is the current etcd index preceded with leading zeroes.
Implemented according to etcd Client API: "Atomically Creating In-Order Keys".
etcd keeps a counter for each operation performed. The etcd index keeps track of this counter, that is, it is the integer associated to the last operation performed in etcd. Given a specified directory EtcdDirectory, createKeyFromCurrentEtcdIndex creates a key in that directory named after the etcd index and associates the value inputed through parameter value to it. This allows to create keys which are strictly ordered by those indexes, since etcd indexes increment monotonously.
EtcdDirectory where the new key will be placed.
EtcdValue to be associated to key.
A Future wrapped around either EtcdSetKeyResponse or EtcdRequestError extending EtcdSetKeyResult.
Deletes a directory from etcd.
Deletes a directory from etcd.
Implemented according to etcd Client API: "Deleting a Directory".
An empty directory can be deleted form etcd by simply specifying EtcdDirectory leading to the directory in etcd. However, for a non-empty directory one must also set the recursive parameter (which defaults to false) to true.
EtcdDirectory to be deleted.
enables deletion of non-empty directories when set to true. Defaults to false.
A Future wrapped around either EtcdCreateDirResponse or EtcdRequestError extending EtcdCreateDirResult.
Deletes a key from etcd.
Deletes a key from etcd.
Implemented according to etcd Client API: "Deleting a key". See also "Atomic Compare-and-Delete".
Optionally etcd allows to conditionally delete a key. This can be done by setting the conditionOp parameter to any of the case classes extending trait ConditionalDeleteCondition.
EtcdKey to be deleted.
One of case classes KeyMustHaveIndex or KeyMustHaveValue extending ConditionalDeleteCondition. Defaults to None.
A Future wrapped around either EtcdDeleteKeyResponse or EtcdRequestError extending EtcdDeleteKeyResult.
Deletes a member form an etcd cluster.
Deletes a member form an etcd cluster.
Implemented according to etcd Members API: "Delete a member".
A string identifying another member of the etcd cluster.
A Future wrapped around either EtcdConfirmationResponse or EtcdStandardError extending EtcdConfirmationResult.
Deletes a role.
Deletes a role.
Implemented according to etcd Auth and Security API: "API endpoints".
In this case, it suffices to provide the role field in the EtcdRole.
EtcdRole with details of the role to be created or updated.
A Future wrapped around either EtcdConfirmationResponse] or EtcdStandardError. extending EtcdConfirmationResult.
Deletes a user.
Deletes a user.
Implemented according to etcd Auth and Security API: "API endpoints".
In this case, it suffices to provide the user in the EtcdUserRequestForm.
EtcdUserRequestForm containing the details of a given user.
A Future wrapped around either EtcdConfirmationResponse or EtcdStandardError. extending EtcdConfirmationResult.
Disables authentication.
Disables authentication.
Implemented according to etcd Auth and Security API: "API endpoints".
A Future wrapped around either EtcdConfirmationResponse or EtcdStandardError. extending EtcdConfirmationResult.
Enables authentication.
Enables authentication.
Implemented according to etcd Auth and Security API: "API endpoints".
In order to enable authentication, the root user must be created first using EtcdClient.addUpdateUser. After authentication only the root user or users with root rights (for example, with the root role) can access and modify permission resources.
A Future wrapped around either EtcdConfirmationResponse or EtcdStandardError. extending EtcdConfirmationResult.
Checks if authentication is enabled.
Checks if authentication is enabled.
Implemented according to etcd Auth and Security API: "API endpoints".
A Future wrapped around either EtcdGetAuthenticationStatusResponse or EtcdStandardError. extending EtcdGetAuthenticationStatusResult.
Verifies the health of a member of an etcd cluster.
Verifies the health of a member of an etcd cluster.
Implemented according to etcd Admin API: "Checking health of an etcd member node".
A Future wrapped around EtcdGetHealthResult with an error or a response containing a boolean, which evaluates to true if the member is healthy, false otherwise.
Gets the current state of a key in etcd.
Gets the current state of a key in etcd.
Implemented according to etcd Client API: "Get the value of a key".
Note that there is no difference in a GET request for a key and a directory. An GET HTTP request made to a node used as a directory looks the same as a request to a node used as a key. However, there is a difference in terms of a response. The getKey method is intended to handle responses only for requests to nodes used as keys. If it is used to make a request to a directory, it will return an EtcdRequestError with the statusCode field set to 200. This means that etcd accepts the request and returns a response. However EtcdClient does not parse the response. In order to get a response which extracts the JSON returned in the response body into a case class, use EtcdClient.listDir.
EtcdKey whose status is queried.
A Future wrapped around either EtcdGetKeyResponse or EtcdRequestError extending EtcdGetKeyResult
Gets statistics from the leader of a cluster, which holds information of the whole cluster.
Gets statistics from the leader of a cluster, which holds information of the whole cluster.
Implemented according to etcd Client API: "Leader Statistics".
Gets a lsi of members of an etcd cluster.
Gets a lsi of members of an etcd cluster.
Implemented according to etcd Members API: "List members".
A Future wrapped around either EtcdGetMembersResponse or EtcdStandardError extending EtcdGetMembersResult.
Gets a list of details of an existing role.
Gets a list of details of an existing role.
Implemented according to etcd Auth and Security API: "API endpoints".
In this case, it suffices to provide the role field in the EtcdRole.
EtcdRole with details of the role to be created or updated.
A Future wrapped around either EtcdGetRoleDetailsResponse] or EtcdStandardError extending EtcdGetRoleDetailsResult.
Gets a list of existing roles.
Gets a list of existing roles.
Implemented according to etcd Auth and Security API: "API endpoints".
A Future wrapped around either EtcdGetRolesResponse] or EtcdStandardError. extending EtcdGetRolesResult.
Gets statistics from a member of an etcd cluster.
Gets statistics from a member of an etcd cluster.
Implemented according to etcd Client API: "Self Statistics".
Gets statistics about performed operations stored by a node of an etcd cluster.
Gets statistics about performed operations stored by a node of an etcd cluster.
Implemented according to etcd Client API: "Store Statistics".
Gets the details of an existing user including permissions granted to her and her roles
Gets the details of an existing user including permissions granted to her and her roles
Implemented according to etcd Auth and Security API: "API endpoints".
In this case, it suffices to provide the user field in the EtcdUserRequestForm.
EtcdUserRequestForm containing the details of a given user.
A Future wrapped around either EtcdGetUserDetailsResponse or EtcdStandardError. extending EtcdGetUserDetailsResult.
Gets a list of existing users.
Gets a list of existing users.
Implemented according to etcd Auth and Security API: "API endpoints".
A Future wrapped around either EtcdGetUsersResponse or EtcdStandardError. extending EtcdGetUsersResult.
Gets the version of an instance of etcd.
Gets the version of an instance of etcd.
Implemented according to etcd Admin API: "Getting the etcd version".
Lists the elements of a directory.
Lists the elements of a directory.
Implemented according to etcd Client API: "Listing a directory". See also "Atomically Creating In-Order Keys" for information on the sorted parameter.
When the parameter recursive is set to false (as it is by default), it lists the immediate children of the given node. When it is set to true, it also recursively lists subnodes of the directory.
When both parameters recursive and sorted are set to true, the list returned is ordered.
EtcdDirectory to be listed.
recursively gets all subnodes of a directory when set to true.
sorts listed key when set to true in combination with the recursive parameter.
A Future wrapped around either EtcdListDirResponse or EtcdRequestError extending EtcdListDirResult.
Refreshes or unsets the TTL of an existing directory.
Refreshes or unsets the TTL of an existing directory.
Implemented according to etcd Client API: "Using a directory TTL".
Sets a lifespan in seconds for an existing directory. Once it expires, the directory is deleted. Setting ttlOp parameter to None allows to unset TTL.
EtcdDirectory whose TTL is to be updated.
Life span in seconds of the directory. Defaults to None.
A Future wrapped around either EtcdCreateDirResponse or EtcdRequestError extending EtcdCreateDirResult.
Updates the TTL of a key without notifying watchers.
Updates the TTL of a key without notifying watchers.
Implemented according to etcd Client API: "Refreshing key TTL".
When a watch is set, and a key is updated using EtcdClient.setKey, watchers are notified, triggering any operation conditionally set to follow given a particular response. This includes updates to its TTL. etcd allows updating TTL without notifying watches set on a key, thus not causing such side effects. EtcdClient implements this feature in the refreshTTL method. When a TTL is refreshed, its value cannot be updated.
EtcdKey that is to be updated.
Life span in seconds of key-value . Defaults to None.
One of case classes KeyMustExist, KeyMustHaveIndex or KeyMustHaveValue extending CompareAndSwapCondition. Defaults to None.
A Future wrapped around either EtcdSetKeyResponse or EtcdRequestError extending EtcdSetKeyResult.
Sets or updates a key in a specific etcd node; also, sets and unsets TTL.
Sets or updates a key in a specific etcd node; also, sets and unsets TTL.
Implemented according to etcd Client API: "Setting the value of a key". See also "Using key TTL", "Creating a hidden node" and "Atomic Compare-and-Swap".
The value of a key can be updated by choosing the same key, but a different value.
Optionally one can choose a TTL (time to live), which is a lifespan in seconds for the key-value. When it expires, the key is deleted.
It is also possible to update the TTL of a key by specifying a new value for the ttlOp parameter with the same key. A similar effect can be achieved using EtcdClient.refreshTTL, except that this last operation does not notify watchers.
The TTL can be unset by updating the key with the parameter ttlOp set to None and with condition KeyMustExist set to true.
Additionally, etcd allows to conditionally compare and swap values. This can be done by setting the conditionOp parameter to any of the case classes extending trait CompareAndSwapCondition.
EtcdKey that is to be set or updated.
EtcdValue to be associated to key.
Life span in seconds of key-value. Defaults to None.
One of case classes KeyMustExist, KeyMustHaveIndex or KeyMustHaveValue extending CompareAndSwapCondition. Defaults to None.
A Future wrapped around either EtcdSetKeyResponse or EtcdRequestError extending EtcdSetKeyResult.
Sets a watch, which returns a get response if there is a change in a key in etcd.
Sets a watch, which returns a get response if there is a change in a key in etcd.
Implemented according to etcd Client API: "Waiting for a change".
Use case of the waitForKey method:
Optionally, one can choose an etcd modified index for which the watch is being set.
An etcd modified index is the integer associated to the operation modifying the state of a key in etcd.
If an index i
is chosen, such that there were subsequent changes in the state of the key after the operation associated to i
, etcd returns an EtcdGetKeyResponse with the state of the key after the first change registered with indexe greater than i
.
For an index j
greater than the etcd index associated to the last operation performed, the watch will not return a response until a change with an index greater than j
is made.
Also, one can choose to wait for changes in any of the subnodes of a given node. This can be achieved by setting the parameter recursive to true. This parameter defaults to false.
EtcdKey on watch.
EtcdWaitCallback which will return a EtcdGetKeyResponse or a throwable once it is called upon.
EtcdIndex associated to an operation performed on a given key.
waits on changes of subnoded of the specified key, when it is set to true. Defaults to false.
A Future wrapped around either com.eiipii.etcd.client.model.EtcdWaitForKeyAccepted containing the headers of the response or EtcdRequestError.
Create a new EtcdClient instance with authorization configuration.
Create a new EtcdClient instance with authorization configuration.
Be aware that each EtcdClient instance must be closed after it is no longer used.
For an example of a set up of an EtcdClient with authentication see this example in our user's guide.
Case class providing a login and a password used for authorization.
Create a new EtcdClient instance with support for TLS.
Create a new EtcdClient instance with support for TLS.
See the V2 Security Model documentation in order to learn about the possible use cases of etcd with TLS.
The following is an example of a possible configuration with TLS taken from out tests:
val clientCert = this.getClass.getResourceAsStream("/ssl/client.crt") val keyFile = this.getClass.getResourceAsStream("/ssl/client_nopass.PKCS8") val caCert = this.getClass.getResourceAsStream("/ssl/dev-ca.crt") val sslContext = SslContextBuilder.forClient() .trustManager(caCert) .keyManager(clientCert, keyFile) .build() val endpoint: String = s"https://localhost:4001" val etcdCli = new EtcdClient(EtcdDSL.config(endpoint)) val secureCli: EtcdClient = etcdCli.withTLS(sslContext)
Make sure to fill in the details for properly configuring the TLS protocol according to your needs.
Look for io.netty.handler.ssl.SslContext in the Netty Javadoc.
Asynchronously sends HTTP requests to etcd servers and handles outcome responses.
EtcdClient
EtcdClient uses AsyncHttpClient in order to build and send HTTP requests. Its methods were developed to suit the etcd documentation. All methods use Scala Futures and Promises in order to provide an asynchronous implementation.
Depending on the request, either an error will be thrown or a response will be returned. In both cases, there is a case class extending a trait in package model with a name ending in Result, which will be returned containing either the response or information about the error.
For example, when performing an EtcdClient.setKey operation, an EtcdSetKeyResult is expected. The outcome of the operation, either an error or a response, can be accessed considering both cases. An easy way to retrieve a response could be with a
match
statement:Key-Value Methods
The implementation of key-value methods follows the specification given in the etcd Client API. Their purpose is to set, retrieve, modify or delete keys, values and directories in etcd. It is also possible to wait (set a watch) on etcd keys, so as to monitor changes in the server in real time and conditionally set operations depending on the response obtained once a change in the data is registered.
Key-Value methods take as inputs case classes defined in package model. The recommended way of getting input data (EtcdKeys, EtcdDirectorys, hidden nodes and EtcdValues) for key-value methods is using the EtcdModel object.
Statistics
The implementation of methods for retrieving etcd cluster statistics also follows the specification given in the etcd Client API and etcd Admin API.
Authentication Methods
The implementation of authentication methods follows the specification given in the etcd authentication and security API. With the help of these methods, a system administrator can enable authentication and create users and roles with different levels of access to etcd. etcd only allows authentication on authentication methods and key-value methods.
Member Methods
The implementation for member methods follows the specification given in the etcd Members API. They allow an administrator to configure a cluster, by changing the members of a cluster.