ackalctl-file-proxy

Warning

Please consider using ackalctl-http-proxy instead of ackalctl-file-proxy.

ackalctl-file-proxy depends upon ackalctl-http-proxy.

If you use this proxy, you will need to use ackalctl-http-proxy as well.

This proxy upates a file on the host file system with the current list of gRPC health checks. This may increase complexity.

In all other respects, the proxies are functionally equivalent.

Overview

NOTE ackalctl-http-proxy must be running in order to run ackalctl-file-proxy.

You can run the proxy (ackalctl-file-proxy) on a host machine.

The proxy (in conjunction with ackalctl-http-proxy) is used by Prometheus instance(s) to scrape your gRPC health check's metrics.

The proxy authenticates Prometheus requests using your Ackal credentials (${HOME}/.config/ackalctl/credentials.json).

When authorized by Ackal, Prometheus uses the proxy to access Ackal's listr service to discover a list of your gRPC health checks.

ackalctl-file-proxy creates a file on your host containing the list of your gRPC health checks.

Prometheus then uses the file to scrape metrics for each of your gRPC health checks.

Config

Please see Container Images for the current version of ackalctl-file-proxy.

ackalctl-file-proxy looks for its configuration in the following places in this order:

  1. Flags
  2. Environment variables
  3. config.json
NOTE We recommend that you use ${HOME}/.config/ackalctl/config.json

Flags

--customer_id
Your Ackal Customer ID
--filename
Filename to be created by the proxy
--listr
Ackal's listing endpoint (default: https://listr.ack.al)
--period
How long to sleep between calls (default: 5 minutes)
--renew
Ackal's token renewal endpoint (default: renew.ack.al:443)
--yaml
Generate YAML (TRUE) or JSON (FALSE) (default: TRUE)

Environment variables

ACKAL_CUSTOMER_ID
Your Ackal Customer ID
ACKAL_LISTR_ENDPOINT
Ackal's listing endpoint (default: https://listr.ack.al)
ACKAL_RENEW_ENDPOINT
Ackal's token renewal endpoint (default: renew.ack.al:443)

Run

ackalctl-file-proxy

We recommend that you use config.json to configure ackalctl-file-proxy


ackalctl-file-proxy \
--filename="/healthchecks.yml" \
--period="15m"
NOTE
  1. ackalctl-http-proxy must be running in order to run ackalctl-file-proxy
  2. --filename flag specifies where the proxy should write the file containg your health check targets that Prometheus File-based Service Discovery can be configured to scrape.
  3. --period flag specifies how frequently the proxy should discover your gRPC health checks

Prometheus


global:
  scrape_interval: 1m
  evaluation_interval: 1m

scrape_configs:
  - job_name: "ackalctl-file-proxy"
    scheme: http
    proxy_url: http://{ENDPOINT}
    file_sd_configs:
    - refresh_interval: 1m
      files:
      - "/healthchecks.yml"
Note
  1. You must replace the value of {ENDPOINT} with the value you used when you ran the ackalctl-http-proxy container
  2. The proxy_url (pointing to ackalctl-http-proxy) occurs twice in the Prometheus scrape_config configuration. It proxies requests to:
    • Ackal's listr service to obtain the list of your gRPC health checks
    • Your gRPC health check to scrape it for its metrics

Then either run:


PROMETHEUS"=docker.io/prom/prometheus"

docker run \
--detach --rm --tty \
--name="prometheus" \
--volume=${PROMETHEUS}:"/etc/prometheus/prometheus.yml:ro" \
--publish="9090:9090" \
${PROMETHEUS} \
--config.file="/etc/prometheus/prometheus.yml" \
--web.enable-lifecycle

Or restart an existing Prometheus instance to update its configuration:


curl \
--request POST \
http://localhost:9090/-/reload

Developer

ackalctrl-file-proxy implements Prometheus File-based Service Discovery to retireve the metrics for your Ackal gRPC health check targets.