Skip to content
Plugins (183)

consul

stable

Helper functions for building Consul HTTP API requests — path builders, JSON body generators, KV base64 encode/decode, and response parsers.

use plugin consul::{kv_path, kv_put_path, kv_delete_path, …}
17 functions Cloud
Runs with the native Zolo host

Plugin snippets can be edited in the Playground, but native capabilities are executed locally with the Zolo CLI.

/ filter jk navigate Esc clear
Functions (17)
  1. kv_path Build the KV read/write API path
  2. kv_put_path Build the KV PUT API path
  3. kv_delete_path Build the KV DELETE API path
  4. service_register_path Build the service register API path
  5. service_register_body Build service registration JSON body
  6. service_deregister_path Build the service deregister API path
  7. health_check_body Build a health check JSON body
  8. health_check_register_body Build a check registration JSON body
  9. health_service_path Build the health service query path
  10. encode_kv_value Base64-encode a string for KV PUT
  11. decode_kv_value Base64-decode a KV value string
  12. catalog_service_path Build the catalog service query path
  13. catalog_nodes_path Get the catalog nodes API path
  14. catalog_services_path Get the catalog services API path
  15. agent_self_path Get the agent self-info API path
  16. agent_services_path Get the agent services API path
  17. parse_kv_response Parse a Consul KV GET JSON response

From import to result

  1. 01Import only what you use
  2. 02Copy the smallest example
  3. 03Run it with the Zolo CLI

Overview

The consul plugin is a stateless helper library for talking to the Consul HTTP API. It does not open any connections itself — instead it builds the API paths, JSON request bodies, and base64 KV encodings you feed into your own HTTP client, and parses the responses that come back. Every function is a pure transformation of its arguments, so it works the same in the VM, native, and WASM backends.

Reach for this plugin whenever you need to register a service, run a KV read/write/delete, query the catalog, or set up a health check against a Consul agent. Pair the path builders (kv_path, catalog_service_path, health_service_path, …) and body builders (service_register_body, health_check_body) with your HTTP library, and use encode_kv_value / decode_kv_value / parse_kv_response to move values across the base64 boundary that Consul's KV store imposes.

Common patterns

Register a service with the local agent, then build its deregister path for cleanup later:

use plugin consul::{service_register_path, service_register_body, service_deregister_path}

let id = "my-api-1"
let body = service_register_body("my-api", id, "10.0.0.5", 8080, #{1: "http", 2: "v2"})

print("PUT {service_register_path()}")
print(body)

// later, on shutdown
print("PUT {service_deregister_path(id)}")

Write a KV value (base64-encoded) and read it back, decoding the response:

use plugin consul::{kv_put_path, encode_kv_value, kv_path, parse_kv_response}

let put = kv_put_path("myapp/env")
let payload = encode_kv_value("production")
print("PUT {put} body={payload}")

// after GET kv_path("myapp/env")
let raw = '[{"Key":"myapp/env","Value":"cHJvZHVjdGlvbg==","Flags":0,"Session":""}]'
let entry = parse_kv_response(raw)
print("{entry["key"]} = {entry["value"]}")

Discover only the healthy nodes of a service, with a check registered for it:

use plugin consul::{health_check_register_body, health_service_path}

let check = health_check_register_body(
  "api-check", "my-api-1", "http://10.0.0.5:8080/health", "15s"
)
print(check)

let healthy = health_service_path("my-api", true)
print("GET {healthy}")

kv_path(key) → string

Build the KV read/write API path

Returns the Consul v1 KV API path for reading a key, e.g. /v1/kv/myapp/config. Leading slashes in the key are stripped.

use plugin consul::{kv_path}

let path = kv_path("myapp/config")
print(path)

A leading slash on the key is stripped, so these produce the same path:

use plugin consul::{kv_path}

print(kv_path("/myapp/config"))
print(kv_path("myapp/config"))

kv_put_path(key) → string

Build the KV PUT API path

Returns the Consul v1 KV API path for writing a key. Identical to kv_path — both map to /v1/kv/{key} (use HTTP PUT to write).

use plugin consul::{kv_put_path}

let path = kv_put_path("myapp/feature-flag")
print(path)

kv_delete_path(key) → string

Build the KV DELETE API path

Returns the Consul v1 KV API path for deleting a key. Use this with an HTTP DELETE request.

use plugin consul::{kv_delete_path}

let path = kv_delete_path("myapp/old-key")
print(path)

service_register_path() → string

Build the service register API path

Returns the fixed path /v1/agent/service/register for registering services with the local agent.

use plugin consul::{service_register_path}

let path = service_register_path()
print(path)

service_register_body(name, id, address, port, tags) → string

Build service registration JSON body

Builds a JSON body for registering a service with the Consul agent. tags is an optional table of tag strings.

use plugin consul::{service_register_body, service_register_path}

let tags = #{1: "http", 2: "v2"}
let body = service_register_body("my-api", "my-api-1", "10.0.0.5", 8080, tags)
print(body)

The tags table is optional — omit it for an untagged service. The body is emitted as pretty-printed JSON ready to PUT to service_register_path():

use plugin consul::{service_register_body, service_register_path}

let body = service_register_body("worker", "worker-1", "10.0.0.9", 9000, #{})
print("PUT {service_register_path()}")
print(body)

service_deregister_path(id) → string

Build the service deregister API path

Returns the deregister API path /v1/agent/service/deregister/{id} for a service instance.

use plugin consul::{service_deregister_path}

let path = service_deregister_path("my-api-1")
print(path)

health_check_body(name, http_url, interval) → string

Build a health check JSON body

Builds a JSON health check body for an HTTP check. The check uses GET and runs at the given interval (e.g. "10s").

use plugin consul::{health_check_body}

let body = health_check_body("api-health", "http://10.0.0.5:8080/health", "10s")
print(body)

health_check_register_body(name, service_id, http_url, interval) → string

Build a check registration JSON body

Builds a JSON body for registering a health check tied to a specific service ID. Includes ServiceID for association.

use plugin consul::{health_check_register_body}

let body = health_check_register_body(
  "api-check", "my-api-1", "http://10.0.0.5:8080/health", "15s"
)
print(body)

health_service_path(service, passing_only) → string

Build the health service query path

Builds the health service query path. If passing_only is true, appends ?passing=true to return only healthy nodes.

use plugin consul::{health_service_path}

let all_path = health_service_path("my-api", false)
print(all_path)

let healthy_path = health_service_path("my-api", true)
print(healthy_path)

passing_only is optional and defaults to false, so a single argument returns the path for all instances regardless of health:

use plugin consul::{health_service_path}

print(health_service_path("redis"))

encode_kv_value(str) → string

Base64-encode a string for KV PUT

Base64-encodes a string so it can be used as a KV PUT request body. Consul stores all KV values as base64.

use plugin consul::{encode_kv_value}

let encoded = encode_kv_value("production")
print(encoded)

encode_kv_value and decode_kv_value are exact inverses, so a value round-trips unchanged:

use plugin consul::{encode_kv_value, decode_kv_value}

let original = "feature-x=on"
let restored = decode_kv_value(encode_kv_value(original))
print(restored)

decode_kv_value(b64) → string

Base64-decode a KV value string

Base64-decodes a KV value as returned by the Consul API. Use this to read the Value field from a KV GET response.

use plugin consul::{decode_kv_value}

let raw = "cHJvZHVjdGlvbg=="
let value = decode_kv_value(raw)
print(value)

catalog_service_path(service) → string

Build the catalog service query path

Returns the catalog service query path /v1/catalog/service/{service} for looking up all nodes providing a service.

use plugin consul::{catalog_service_path}

let path = catalog_service_path("redis")
print(path)

catalog_nodes_path() → string

Get the catalog nodes API path

Returns the fixed path /v1/catalog/nodes for listing all registered nodes in the catalog.

use plugin consul::{catalog_nodes_path}

let path = catalog_nodes_path()
print(path)

catalog_services_path() → string

Get the catalog services API path

Returns /v1/catalog/services for listing all registered services.

use plugin consul::{catalog_services_path}

let path = catalog_services_path()
print(path)

agent_self_path() → string

Get the agent self-info API path

Returns /v1/agent/self, the path for querying the local Consul agent info.

use plugin consul::{agent_self_path}

let path = agent_self_path()
print(path)

agent_services_path() → string

Get the agent services API path

Returns /v1/agent/services for listing all services registered with the local agent.

use plugin consul::{agent_services_path}

let path = agent_services_path()
print(path)

parse_kv_response(json_str) → table

Parse a Consul KV GET JSON response

Parses the JSON body from a Consul KV GET request. Automatically base64- decodes the Value field. Returns a table with key, value, flags, and session.

use plugin consul::{parse_kv_response}

let json = '[{"Key":"myapp/env","Value":"cHJvZHVjdGlvbg==","Flags":0,"Session":""}]'
let entry = parse_kv_response(json)
print("key: {entry["key"]}, value: {entry["value"]}")

The returned table also carries flags (an integer) and session (the lock-session string, empty when the key is unlocked):

use plugin consul::{parse_kv_response}

let json = '[{"Key":"locks/leader","Value":"bm9kZS1h","Flags":42,"Session":"abc-123"}]'
let entry = parse_kv_response(json)
print("flags={entry["flags"]} session={entry["session"]}")
View source code

Global index

Find your way through Zolo

Try an idea

Start here

9 results

9 results
en