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.


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.


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


Your Ackal Customer ID
Filename to be created by the proxy
Ackal's listing endpoint (default:
How long to sleep between calls (default: 5 minutes)
Ackal's token renewal endpoint (default:
Generate YAML (TRUE) or JSON (FALSE) (default: TRUE)

Environment variables

Your Ackal Customer ID
Ackal's listing endpoint (default:
Ackal's token renewal endpoint (default:



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

ackalctl-file-proxy \
--filename="/healthchecks.yml" \
  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


  scrape_interval: 1m
  evaluation_interval: 1m

  - job_name: "ackalctl-file-proxy"
    scheme: http
    proxy_url: http://{ENDPOINT}
    - refresh_interval: 1m
      - "/healthchecks.yml"
  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:


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

Or restart an existing Prometheus instance to update its configuration:

curl \
--request POST \


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