Struct Client

pub struct Client { /* private fields */ }

The Consul API client.

Implementations

impl Client

pub fn new() -> Self

Creates a new client with the default configuration.

pub async fn agent_checks( &self, q: &FilterRequestQuery, ) -> Result<HashMap<String, HealthCheck>>

List Checks This endpoint returns all checks that are registered with the local agent. These checks were either provided through configuration files or added dynamically using the HTTP API.

pub async fn agent_check_register(&self, b: &CheckDefinition) -> Result<bool>

Register Check This endpoint adds a new check to the local agent. Checks may be of script, HTTP, TCP, UDP, or TTL type. The agent is responsible for managing the status of the check and keeping the Catalog in sync.

pub async fn agent_check_deregister( &self, q: &DeregisterCheckRequestQuery, ) -> Result<bool>

Deregister Check This endpoint remove a check from the local agent. The agent will take care of deregistering the check from the catalog. If the check with the provided ID does not exist, no action is taken.

pub async fn agent_check_pass( &self, q: &AgentTTLCheckRequestQuery, ) -> Result<bool>

TTL Check Pass This endpoint is used with a TTL type check to set the status of the check to passing and to reset the TTL clock.

pub async fn agent_check_warn( &self, q: &AgentTTLCheckRequestQuery, ) -> Result<()>

TTL Check Warn This endpoint is used with a TTL type check to set the status of the check to warning and to reset the TTL clock.

pub async fn agent_check_fail( &self, q: &AgentTTLCheckRequestQuery, ) -> Result<bool>

TTL Check Fail This endpoint is used with a TTL type check to set the status of the check to critical and to reset the TTL clock.

pub async fn agent_check_update( &self, q: &AgentTTLCheckUpdateRequestQuery, b: &AgentTTLCheckUpdateRequestBody, ) -> Result<bool>

TTL Check Update This endpoint is used with a TTL type check to set the status of the check and to reset the TTL clock.

pub async fn agent_services( &self, q: &FilterRequestQuery, ) -> Result<HashMap<String, AgentService>>

List Services This endpoint returns all the services that are registered with the local agent. These services were either provided through configuration files or added dynamically using the HTTP API.

pub async fn agent_service_configuration( &self, q: &ServiceConfigurationRequestQuery, ) -> Result<Option<AgentService>>

pub async fn agent_get_service_health_by_name<S: Into<String>>( &self, service_name: S, q: &LocalServiceHealthByNameRequestQuery, ) -> Result<Vec<AgentServiceChecksInfo>>

Get local service health Retrieve an aggregated state of service(s) on the local agent by name.

This endpoints support JSON format and text/plain formats, JSON being the default. In order to get the text format, you can append ?format=text to the URL or use Mime Content negotiation by specifying a HTTP Header Accept starting with text/plain.

pub async fn agent_get_service_health_by_id<S: Into<String>>( &self, service_id: S, q: &LocalServiceHealthByIDRequestQuery, ) -> Result<Option<AgentServiceChecksInfo>>

Get local service health by ID Retrieve the health state of a specific service on the local agent by ID.

pub async fn agent_register_service( &self, q: &RegisterServiceRequestQuery, b: &ServiceDefinition, ) -> Result<bool>

Register Service This endpoint adds a new service, with optional health checks, to the local agent.

The agent is responsible for managing the status of its local services, and for sending updates about its local services to the servers to keep the global catalog in sync.

pub async fn agent_deregister_service<S: Into<String>>( &self, service_id: S, q: &DeregisterServiceRequestQuery, ) -> Result<bool>

Deregister Service This endpoint removes a service from the local agent. If the service does not exist, no action is taken.

The agent will take care of deregistering the service with the catalog. If there is an associated check, that is also deregistered.

pub async fn agent_enable_maintenance_mode( &self, q: &EnableMaintenanceModeRequestQuery, ) -> Result<bool>

Enable Maintenance Mode

This endpoint places a given service into “maintenance mode”. During maintenance mode, the service will be marked as unavailable and will not be present in DNS or API queries. This API call is idempotent. Maintenance mode is persistent and will be automatically restored on agent restart.

pub async fn agent_connect_authorize( &self, q: &ConnectAuthorizeRequestQuery, b: &ConnectAuthorizeRequest, ) -> Result<ConnectAuthorizeRequestReply>

pub async fn catalog_register_entity( &self, q: &CatalogRegisterEntityQuery, b: &RegisterRequest, ) -> Result<bool>

Catalog Register Entity This endpoint is a low-level mechanism for registering or updating entries in the catalog. It is usually preferable to instead use the agent endpoints for registration as they are simpler and perform anti-entropy.

pub async fn catalog_deregister_entity( &self, q: &CatalogDeregisterEntityQuery, b: &DeregisterRequest, ) -> Result<bool>

Catalog Deregister Entity This endpoint is a low-level mechanism for directly removing entries from the Catalog. It is usually preferable to instead use the agent endpoints for deregistration as they are simpler and perform anti-entropy.

pub async fn catalog_list_datacenters(&self) -> Result<Vec<String>>

Catalog List Datacenters This endpoint returns the list of all known datacenters. The datacenters will be sorted in ascending order based on the estimated median round trip time from the server to the servers in that datacenter.

pub async fn catalog_list_nodes(&self) -> Result<Vec<Node>>

Catalog List Nodes This endpoint and returns the nodes registered in a given datacenter.

pub async fn catalog_list_services( &self, q: &CatalogListServicesQuery, ) -> Result<HashMap<String, Vec<String>>>

Catalog List Services This endpoint returns the services registered in a given datacenter.

pub async fn catalog_list_nodes_for_service<S: Into<String>>( &self, service_name: S, q: &CatalogListNodesForServiceQuery, ) -> Result<Vec<ServiceNode>>

Catalog List Nodes for Service This endpoint returns the nodes providing a service in a given datacenter.

pub async fn catalog_list_nodes_for_mesh_capable_service<S: Into<String>>( &self, service: S, q: &CatalogListNodesForServiceQuery, ) -> Result<Vec<ServiceNode>>

List Nodes for Mesh-capable Service This endpoint returns the nodes providing a mesh-capable service in a given datacenter. This will include both proxies and native integrations. A service may register both mesh-capable and incapable services at the same time, so this endpoint may be used to filter only the mesh-capable endpoints.

pub async fn catalog_node_services<S: Into<String>>( &self, node_name: S, q: &CatalogNodeServicesQuery, ) -> Result<Option<NodeServices>>

Retrieve Map of Services for a Node This endpoint returns the node’s registered services.

pub async fn catalog_gateway_services<S: Into<String>>( &self, gateway: S, q: &CatalogGatewayServicesQuery, ) -> Result<Vec<GatewayService>>

List Services for Gateway This endpoint returns the services associated with an ingress gateway or terminating gateway.

pub async fn event_fire<S: Into<String>>( &self, name: S, body: Option<Vec<u8>>, q: &EventFireQuery, ) -> Result<bool>

Fire Event This endpoint triggers a new user event.

pub async fn event_list(&self, q: &EventListQuery) -> Result<Vec<UserEvent>>

List Events This endpoint returns the most recent events (up to 256) known by the agent. As a consequence of how the event command works, each agent may have a different view of the events. Events are broadcast using the gossip protocol, so they have no global ordering nor do they make a promise of delivery.

pub async fn health_list_nodes<S: Into<String>>( &self, node: S, q: &HealthListNodesQuery, ) -> Result<Vec<HealthCheck>>

List Checks for Node This endpoint returns the checks specific to the node provided on the path.

pub async fn health_list_services<S: Into<String>>( &self, service: S, q: &HealthListServicesQuery, ) -> Result<Vec<HealthCheck>>

List Checks for Service This endpoint returns the checks associated with the service provided on the path.

pub async fn health_list_service_instances<S: Into<String>>( &self, service: S, q: &HealthListServiceInstancesQuery, ) -> Result<Vec<CheckServiceNode>>

List Service Instances for Service This endpoint returns the service instances providing the service indicated on the path. Users can also build in support for dynamic load balancing and other features by incorporating the use of health checks.

pub async fn health_list_service_instances_for_mesh_capable<S: Into<String>>( &self, service: S, q: &HealthListServiceInstancesQuery, ) -> Result<Vec<CheckServiceNode>>

List Service Instances for Mesh-enabled Service

This endpoint returns the service instances providing a mesh-capable service in a given datacenter. This will include both proxies and native integrations. A service may register both mesh-capable and incapable services at the same time, so this endpoint may be used to filter only the mesh-capable endpoints.

pub async fn health_list_service_instances_for_ingress_gateways<S: Into<String>>( &self, service: S, q: &HealthListServiceInstancesQuery, ) -> Result<Vec<CheckServiceNode>>

List Service Instances for Ingress Gateways Associated with a Service

This API is available in Consul versions 1.8.0 and later.

This endpoint returns the service instances providing an ingress gateway for a service in a given datacenter.

pub async fn health_list_state( &self, state: Health, q: &HealthListStateQuery, ) -> Result<Vec<HealthCheck>>

List Checks in State

This endpoint returns the checks in the state provided on the path.

pub async fn kv_read_key<S: Into<String>>( &self, key: S, q: &KVReadKeyQuery, ) -> Result<Option<Vec<u8>>>

Read Key This endpoint returns the specified key. If no key exists at the given path, a 404 is returned instead of a 200 response.

pub async fn kv_create_or_update_key<S: Into<String>>( &self, key: S, b: Vec<u8>, q: &KVCreateOrUpdateKeyQuery, ) -> Result<bool>

Create/Update Key This endpoint updates the value of the specified key. If no key exists at the given path, the key will be created.

pub async fn kv_delete_key<S: Into<String>>( &self, key: S, q: &KVDeleteKeyQuery, ) -> Result<bool>

Delete Key This endpoint deletes a single key or all keys sharing a prefix.

pub async fn status_leader(&self, q: &StatusQuery) -> Result<String>

Get Raft Leader

This endpoint returns the Raft leader for the datacenter in which the agent is running.

pub async fn status_peers(&self, q: &StatusQuery) -> Result<Vec<String>>

List Raft Peers

This endpoint retrieves the Raft peers for the datacenter in which the agent is running. This list of peers is strongly consistent and can be useful in determining when a given server has successfully joined the cluster.

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.