Package org.kiwiproject.consul

Class AgentClient

java.lang.Object
org.kiwiproject.consul.AgentClient
public class AgentClient extends Object
HTTP Client for /v1/agent/ endpoints.
See Also:

  • Field Details

    • http

      protected final Http http

  • Method Details

    • isRegistered

      public boolean isRegistered(String serviceId)
      Indicates whether a particular service is registered with the local Consul agent.
      Parameters:
      serviceId - the ID of the service to check
      Returns:
      true if a particular service is registered with the local Consul agent, otherwise false.

    • ping

      public void ping()
      Pings the Consul Agent.

    • register

      public void register(int port, long ttl, String name, String id, List<String> tags, Map<String,String> meta)
      Registers the client as a service with Consul with a ttl check.
      Parameters:
      port - The public facing port of the service to register with Consul.
      ttl - Time to live in seconds for the Consul dead man's switch.
      name - Service name to register.
      id - Service id to register.
      tags - Tags to register with.
      meta - Meta to register with.

    • register

      public void register(int port, String args, long interval, String name, String id, List<String> tags, Map<String,String> meta)
      Registers the client as a service with Consul with a script-based check.
      Parameters:
      port - The public facing port of the service to register with Consul.
      args - Specifies command argument to run to update the status of the check.
      interval - Health script run interval in seconds.
      name - Service name to register.
      id - Service id to register.
      tags - Tags to register with.
      meta - Meta to register with.

    • register

      public void register(int port, List<String> args, long interval, String name, String id, List<String> tags, Map<String,String> meta)
      Registers the client as a service with Consul with a script-based check.
      Parameters:
      port - The public facing port of the service to register with Consul.
      args - Specifies command argument to run to update the status of the check.
      interval - Health script run interval in seconds.
      name - Service name to register.
      id - Service id to register.
      tags - Tags to register with.
      meta - Meta to register with.

    • register

      public void register(int port, URL http, long interval, String name, String id, List<String> tags, Map<String,String> meta)
      Registers the client as a service with Consul with an HTTP-based check
      Parameters:
      port - The public facing port of the service to register with Consul.
      http - Health check URL.
      interval - Health script run interval in seconds.
      name - Service name to register.
      id - Service id to register.
      tags - Tags to register with.
      meta - Meta to register with.

    • register

      public void register(int port, com.google.common.net.HostAndPort tcp, long interval, String name, String id, List<String> tags, Map<String,String> meta)
      Registers the client as a service with Consul with a TCP-based check
      Parameters:
      port - The public facing port of the service to register with Consul.
      tcp - Health check TCP host and port.
      interval - Health script run interval in seconds.
      name - Service name to register.
      id - Service id to register.
      tags - Tags to register with.
      meta - Meta to register with.

    • register

      public void register(int port, Registration.RegCheck check, String name, String id, List<String> tags, Map<String,String> meta)
      Registers the client as a service with Consul with an existing Registration.RegCheck
      Parameters:
      port - The public facing port of the service to register with Consul.
      check - The health check to run periodically. Can be null.
      name - Service name to register.
      id - Service id to register.
      tags - Tags to register with.
      meta - Meta to register with.

    • register

      public void register(int port, List<Registration.RegCheck> checks, String name, String id, List<String> tags, Map<String,String> meta)
      Registers the client as a service with Consul with multiple checks
      Parameters:
      port - The public facing port of the service to register with Consul.
      checks - The health checks to run periodically.
      name - Service name to register.
      id - Service id to register.
      tags - Tags to register with.
      meta - Meta to register with.

    • register

      public void register(Registration registration, QueryOptions options, QueryParameterOptions queryParameterOptions)
      Registers the client as a service with Consul. Registration enables the use of checks.
      Parameters:
      registration - The registration payload.
      options - An optional QueryOptions instance.
      queryParameterOptions - The Query Parameter Options to use.

    • register

      public void register(Registration registration, QueryOptions options)

    • register

      public void register(Registration registration)

    • deregister

      public void deregister(String serviceId, QueryOptions options)
      De-register a particular service from the Consul Agent.
      Parameters:
      serviceId - the ID of the service to deregister
      options - the query options to use

    • deregister

      public void deregister(String serviceId)
      De-register a particular service from the Consul Agent.
      Parameters:
      serviceId - the ID of the service to deregister

    • registerCheck

      public void registerCheck(String checkId, String name, String script, long interval)
      Registers a script Health Check with the Agent.
      Parameters:
      checkId - The Check ID to use. Must be unique for the Agent.
      name - The Check Name.
      script - Health script for Consul to use.
      interval - Health script run interval in seconds.

    • registerCheck

      public void registerCheck(String checkId, String name, URL http, long interval)
      Registers an HTTP Health Check with the Agent.
      Parameters:
      checkId - The Check ID to use. Must be unique for the Agent.
      name - The Check Name.
      http - Health check URL.
      interval - Health script run interval in seconds.

    • registerCheck

      public void registerCheck(String checkId, String name, com.google.common.net.HostAndPort tcp, long interval)
      Registers a TCP Health Check with the Agent.
      Parameters:
      checkId - The Check ID to use. Must be unique for the Agent.
      name - The Check Name.
      tcp - Health check TCP host and port.
      interval - Health script run interval in seconds.

    • registerCheck

      public void registerCheck(String checkId, String name, List<String> args, long interval, String notes)
      Registers a script Health Check with the Agent.
      Parameters:
      checkId - The Check ID to use. Must be unique for the Agent.
      name - The Check Name.
      args - Health script for Consul to use.
      interval - Health script run interval in seconds.
      notes - Human-readable notes. Not used by Consul.

    • registerCheck

      public void registerCheck(String checkId, String name, String args, long interval, String notes)
      Registers a script Health Check with the Agent.
      Parameters:
      checkId - The Check ID to use. Must be unique for the Agent.
      name - The Check Name.
      args - Specifies command argument to run to update the status of the check.
      interval - Health script run interval in seconds.
      notes - Human-readable notes. Not used by Consul.

    • registerCheck

      public void registerCheck(String checkId, String name, URL http, long interval, String notes)
      Registers an HTTP Health Check with the Agent.
      Parameters:
      checkId - The Check ID to use. Must be unique for the Agent.
      name - The Check Name.
      http - Health check URL.
      interval - Health script run interval in seconds.
      notes - Human-readable notes. Not used by Consul.

    • registerCheck

      public void registerCheck(String checkId, String name, com.google.common.net.HostAndPort tcp, long interval, String notes)
      Registers a TCP Health Check with the Agent.
      Parameters:
      checkId - The Check ID to use. Must be unique for the Agent.
      name - The Check Name.
      tcp - Health check TCP host and port.
      interval - Health script run interval in seconds.
      notes - Human-readable notes. Not used by Consul.

    • registerCheck

      public void registerCheck(String checkId, String name, long ttl)
      Registers a Health Check with the Agent.
      Parameters:
      checkId - The Check ID to use. Must be unique for the Agent.
      name - The Check Name.
      ttl - Time to live for the Consul dead man's switch.

    • registerCheck

      public void registerCheck(String checkId, String name, long ttl, String notes)
      Registers a Health Check with the Agent.
      Parameters:
      checkId - The Check ID to use. Must be unique for the Agent.
      name - The Check Name.
      ttl - Time to live for the Consul dead man's switch.
      notes - Human-readable notes. Not used by Consul.

    • registerCheck

      public void registerCheck(Check check)
      Registers a Health Check with the Agent.
      Parameters:
      check - The Check to register.

    • deregisterCheck

      public void deregisterCheck(String checkId)
      De-registers a Health Check with the Agent
      Parameters:
      checkId - the id of the Check to deregister

    • getAgent

      public Agent getAgent()
      Retrieves the Agent's configuration and member information.

      GET /v1/agent/self

      Returns:
      The Agent information.

    • getChecks

      public Map<String,HealthCheck> getChecks()
      Retrieves all checks registered with the Agent.

      GET /v1/agent/checks

      Returns:
      Map of Check ID to Checks.

    • getChecks

      public Map<String,HealthCheck> getChecks(QueryOptions queryOptions)
      Retrieves all checks registered with the Agent.

      GET /v1/agent/checks

      Parameters:
      queryOptions - The Query Options to use.
      Returns:
      Map of Check ID to Checks.

    • getServices

      public Map<String,Service> getServices()
      Retrieves all services registered with the Agent.

      GET /v1/agent/services

      Returns:
      Map of Service ID to Services.

    • getServices

      public Map<String,Service> getServices(QueryOptions queryOptions)
      Retrieves all services registered with the Agent.

      GET /v1/agent/services

      Parameters:
      queryOptions - The Query Options to use.
      Returns:
      Map of Service ID to Services.

    • getService

      public ConsulResponse<FullService> getService(String id, QueryOptions queryOptions) throws NotRegisteredException
      Retrieves all information about a service.

      GET /v1/agent/service/:service_id

      Parameters:
      id - The service id.
      queryOptions - The Query Options to use.
      Returns:
      A ConsulResponse containing FullService object.
      Throws:
      NotRegisteredException - if the service is not registered

    • getService

      public void getService(String id, QueryOptions queryOptions, ConsulResponseCallback<FullService> callback)
      Retrieves all information about a service.

      GET /v1/agent/service/:service_id

      Parameters:
      id - The service id.
      queryOptions - The Query Options to use.
      callback - Callback implemented by callee to handle results.

    • getMembers

      public List<Member> getMembers()
      Retrieves all members that the Agent can see in the gossip pool.

      GET /v1/agent/members

      Returns:
      List of Members.

    • getMembers

      public List<Member> getMembers(QueryOptions queryOptions)
      Retrieves all members that the Agent can see in the gossip pool.

      GET /v1/agent/members

      Parameters:
      queryOptions - The Query Options to use.
      Returns:
      List of Members.

    • forceLeave

      public void forceLeave(String node)
      GET /v1/agent/force-leave/{node}

      Instructs the agent to force a node into the "left" state.

      Parameters:
      node - Node name

    • forceLeave

      public void forceLeave(String node, QueryParameterOptions queryParameterOptions)
      GET /v1/agent/force-leave/{node}

      Instructs the agent to force a node into the "left" state.

      Parameters:
      node - Node name
      queryParameterOptions - The Query Parameters Options to use.

    • check

      public void check(String checkId, State state, String note) throws NotRegisteredException
      Checks in with Consul.
      Parameters:
      checkId - The Check ID to check in.
      state - The current state of the Check.
      note - Any note to associate with the Check.
      Throws:
      NotRegisteredException - if the service has not registered

    • checkTtl

      public void checkTtl(String serviceId, State state, String note) throws NotRegisteredException
      Prepends the default TTL prefix to the serviceId to produce a check id, then delegates to check(String, State, String).

      This method only works with TTL checks that have not been given a custom name.

      Parameters:
      serviceId - the ID of the service to check
      state - the state to use in the check-in
      note - the note to add to the check-in
      Throws:
      NotRegisteredException - if the service has not registered

    • pass

      public void pass(String serviceId) throws NotRegisteredException
      Sets a TTL service check to "passing" state
      Parameters:
      serviceId - the ID of the service to set as passing
      Throws:
      NotRegisteredException - if the service has not registered

    • pass

      public void pass(String serviceId, String note) throws NotRegisteredException
      Sets a TTL service check to "passing" state with a note
      Parameters:
      serviceId - the ID of the service to set as passing
      note - the note to set on the check
      Throws:
      NotRegisteredException - if the service has not registered

    • warn

      public void warn(String serviceId) throws NotRegisteredException
      Sets a TTL service check to "warning" state.
      Parameters:
      serviceId - serviceId the ID of the service to set as warn
      Throws:
      NotRegisteredException - if the service has not registered

    • warn

      public void warn(String serviceId, String note) throws NotRegisteredException
      Sets a TTL service check to "warning" state with a note.
      Parameters:
      serviceId - serviceId the ID of the service to set as warn
      note - the note to set on the check
      Throws:
      NotRegisteredException - if the service has not registered

    • fail

      public void fail(String serviceId) throws NotRegisteredException
      Sets a TTL service check to "critical" state.
      Parameters:
      serviceId - serviceId the ID of the service to set as critical/fail
      Throws:
      NotRegisteredException - if the service has not registered

    • fail

      public void fail(String serviceId, String note) throws NotRegisteredException
      Sets a TTL service check to "critical" state with a note.
      Parameters:
      serviceId - serviceId the ID of the service to set as critical/fail
      note - the note to set on the check
      Throws:
      NotRegisteredException - if the service has not registered

    • passCheck

      public void passCheck(String checkId) throws NotRegisteredException
      Sets a TTL check to "passing" state
      Parameters:
      checkId - the ID of the check to set as passing
      Throws:
      NotRegisteredException - if the service has not registered

    • passCheck

      public void passCheck(String checkId, String note) throws NotRegisteredException
      Sets a TTL check to "passing" state with a note
      Parameters:
      checkId - the ID of the check to set as passing
      note - the note to set on the check
      Throws:
      NotRegisteredException - if the service has not registered

    • warnCheck

      public void warnCheck(String checkId) throws NotRegisteredException
      Sets a TTL check to "warning" state.
      Parameters:
      checkId - the ID of the check to set as "warning"
      Throws:
      NotRegisteredException - if the service has not registered

    • warnCheck

      public void warnCheck(String checkId, String note) throws NotRegisteredException
      Sets a TTL check to "warning" state with a note.
      Parameters:
      checkId - the ID of the check to set as "warning"
      note - the note to set on the check
      Throws:
      NotRegisteredException - if the service has not registered

    • failCheck

      public void failCheck(String checkId) throws NotRegisteredException
      Sets a TTL check to "critical" state.
      Parameters:
      checkId - the ID of the check to set as critical/fail
      Throws:
      NotRegisteredException - if the service has not registered

    • failCheck

      public void failCheck(String checkId, String note) throws NotRegisteredException
      Sets a TTL check to "critical" state with a note.
      Parameters:
      checkId - the ID of the check to set as critical/fail
      note - the note to set on the check
      Throws:
      NotRegisteredException - if the service has not registered

    • join

      public boolean join(String address)
      GET /v1/agent/join/{address}

      Instructs the agent to join a node.

      Parameters:
      address - The address to join.
      Returns:
      true if successful, otherwise false.

    • join

      public boolean join(String address, boolean wan)
      GET /v1/agent/join/{address}?wan=wan

      Instructs the agent to join a node.

      Parameters:
      address - The address to join.
      wan - Use WAN pool.
      Returns:
      true if successful, otherwise false.

    • join

      public boolean join(String address, QueryOptions queryOptions)
      GET /v1/agent/join/{address}?queryOptions

      Instructs the agent to join a node.

      Parameters:
      address - The address to join.
      queryOptions - The Query Options to use.
      Returns:
      true if successful, otherwise false.

    • toggleMaintenanceMode

      public void toggleMaintenanceMode(String serviceId, boolean enable)
      Toggles maintenance mode for a service ID.
      Parameters:
      serviceId - The service ID.
      enable - true if the service should be in maintenance mode, otherwise false.

    • toggleMaintenanceMode

      public void toggleMaintenanceMode(String serviceId, boolean enable, String reason)
      Toggles maintenance mode for a service ID.
      Parameters:
      serviceId - The service ID.
      enable - true if the service should be in maintenance mode, otherwise false.
      reason - The reason for maintenance mode.

    • toggleMaintenanceMode

      public void toggleMaintenanceMode(String serviceId, QueryOptions queryOptions)
      Toggles maintenance mode for a service ID.
      Parameters:
      serviceId - The service ID.
      queryOptions - The Query Options to use.

    • getConfig

      public ClientConfig getConfig()

    • getEventHandler

      public ClientEventHandler getEventHandler()