ackalctl

ackalctl [flags] <verb> <type>

Types

TypeDescription
CheckThe configuration of a gRPC health check. A Check is defined by the endpoint being checked, the period at which it the endpoint is checked and the source locations from where it is checked.
CustomerA Customer represents at least one User and at least one Domain. A User is associated with at least one Customer. The Customer identifier (customer_id) is used to interact with ackalctl commands.
DomainA Domain is a reference to a DNS domain name.
LocationA Location is a source location where a gRPC health check can be deployed.
UserAn individual user. The user authenticates to Ackal using a 3rd-party OAuth system (e.g. Google) and has a Stripe subscription for Ackal. There are no ackalctl commands for users.

Verbs

VerbDescription
CreateCreate a resource.
DeleteDelete a resource.
GetGet (details of) a resource.
ListList all resources.
UpdateUpdate a resource.
VerifyVerify a resource (only applies to Domains).

Configuration

Please see Container Images for the current version of ackalctl.

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

  1. Flags (See Global Flags)
  2. Environment variables
  3. config.json

Environment variables

The following environment variables may be used:

VariableDescription
ACKAL_CUSTOMER_IDYour Customer ID
ACKAL_SERVICE_ENDPOINTAckal's endpoint (default: service.ack.al:443)
ACKAL_RENEW_ENDPOINTAckal's token renewal endpoint (default: renew.ack.al:443)

Credentials

ackalctl looks for the user's credentials in ${HOME}/.config/credentials.json.

Here's an example credentials.json:


{
  "jwt": "...",
  "refresh_token": "...",
  "expiration": 0
}
NOTE No other properties are supported.

If the file exists, ackalctl uses the property values to authenticate the user.

If the file does not exist, the user will be unable to authenticate ackalctl commands.

Global Flags

NOTE If not defined in Configuration File, --ackal, --customer_id and --renew are required by all ackalctl commands.. The --format flag may be added to any command.
--ackal
The socket (host:port) that describes the Ackal service. If used, this flag overrides the value of services.ackal in the Configuration File.
--customer_id
The user’s Customer ID. If used, this flag overrides the value of customer.id in the Configuration File.
--format
Format the command output as tabular text, JSON or YAML. JSON and YAML are useful when scripting ackalctl commands. The output can be used with e.g. jq for JSON and e.g. yq for YAML.
--renew
The socket (host:port) that describes the Ackal token renewal service. If use, this flag overrides the value of services.renew in the Configuration File.

Check

The configuration of a gRPC health check. A Check is defined by the endpoint being checked, the period at which it the endpoint is checked and the source locations from where it is checked.

ackalctl create check

Create a gRPC health check for a set of services, from a set of locations, with a specific frequency against an endpoint.

NOTE The combination of an endpoint and period uniquely specifies a health check. Creating a health check will replace existing health checks with the same endpoint and period
If successful, the command returns the Check ID.

Synopsis


ackalctl \
--endpoint=ENDPOINT
--period=PERIOD
--location_ids=[LOCATION_ID,...]
--services=[SERVICE,SERVICE,...]
create check

Flags

--endpoint
The socket (host:port) of the gRPC service to be monitored.
--period
How often the test is run. The value corresponds to a Golang Duration string e.g. 120s, 1h, 1h30m i.e. 2 minutes, 60 minutes, 90 minutes respectively. ackalctl list checks lists Checks with the period normalized to seconds.
--location_ids
A comma-separated list of Location IDs from which health checks should be run. Location IDs may be determined with ackalctl list locations
--services
A comma-separated list of gRPC Services to be health checked. Empty string ("") used to check overall service health.

Example


ackalctl \  
--endpoint="healthcheck-server.ack.al:443"  
--period="120s"  
--location_ids="london,the-dalles"  
--services="ServiceA,ServiceB"
create check

ackalctl delete check

Delete a gRPC health check.

NOTE The combination of an endpoint and period uniquely specifics a health check. In order to delete a health check, you will need to specify both an endpoint and a period.
.

Synopsis


ackalctl \
--endpoint=ENDPOINT
--period=PERIOD
delete check

Flags

--endpoint
The socket (host:port) of the gRPC service to be monitored.
--period
How often the test is run. The value corresponds to a Golang Duration string e.g. 120s, 1h, 1h30m i.e. 2 minutes, 60 minutes, 90 minutes respectively. ackalctl list checks lists Checks with the period normalized to seconds.

Example


ackalctl \  
--endpoint="healthcheck-server.ack.al:443"  
--period="120s"
delete check

ackalctl get check

Get (details of) a gRPC health check.
If successful, returns details of the health check.

Synopsis


ackalctl \
--endpoint=ENDPOINT
--period=PERIOD
get check

Flags

--endpoint
The socket (host:port) of the gRPC service to be monitored.
--period
How often the test is run. The value corresponds to a Golang Duration string e.g. 120s, 1h, 1h30m i.e. 2 minutes, 60 minutes, 90 minutes respectively. ackalctl list checks lists Checks with the period normalized to seconds.

Example


ackalctl \  
--endpoint="healthcheck-server.ack.al:443"  
--period="120s"
get check

ackalctl list check

Lists the gRPC health checks.

Synopsis


ackalctl \
list check

Flags

Note No additional flags are used by this command.

Example


ackalctl \
list check

ackalctl update check

Update a gRPC health check.

Synopsis


ackalctl \
--endpoint=ENDPOINT
--period=PERIOD
--services=[SERVICE,SERVICE,...]
--enabled=ENABLED
update check

Flags

--endpoint
The socket (host:port) of the gRPC service to be monitored.
--period
How often the test is run. The value corresponds to a Golang Duration string e.g. 120s, 1h, 1h30m i.e. 2 minutes, 60 minutes, 90 minutes respectively. ackalctl list checks lists Checks with the period normalized to seconds.
--services
A comma-separated list of gRPC Services to be health checked. Empty string ("") used to check overall service health.
--enabled

Example


ackalctl \  
--endpoint="healthcheck-server.ack.al:443"  
--period="120s"  
--services="ServiceA,ServiceB"  
--enabled="false"
update check

Customer

A Customer represents at least one User and at least one Domain. A User is associated with at least one Customer. The Customer identifier (customer_id) is used to interact with ackalctl commands.

ackalctl get customer

Get (details of) a customer

Synopsis


ackalctl \
get customer

Flags

Note No additional flags are used by this command.

Example


ackalctl \
get customer

ackalctl update customer

Update a customer

Synopsis


ackalctl \
--enabled=ENABLED
update customer

Flags

--enabled

Example


ackalctl \  
--enabled="false"
update customer

Domain

A Domain is a reference to a DNS domain name.

ackalctl create domain

Create a reference to a domain name.

NOTE Once a reference to a domain is created, ownership of the domain must be verified. Use ackalctl get domain to obtain the verification code that Ackal has generated for the domain, update the domain's custom records with a TXT entry for the domain, see Verifying Domains and then ackalctl verify domain to ensure the domain verifies correctly.

Synopsis


ackalctl \
--domain_name=DOMAIN_NAME
create domain

Flags

--domain_name

Example


ackalctl \  
--domain_name="ack.al"
create domain

ackalctl delete domain

Delete a reference to a domain name.

Synopsis


ackalctl \
--domain_name=DOMAIN_NAME
delete domain

Flags

--domain_name

Example


ackalctl \  
--domain_name="ack.al"
delete domain

ackalctl get domain

Get (details of) a domain.

Synopsis


ackalctl \
--domain_name=DOMAIN_NAME
get domain

Flags

--domain_name

Example


ackalctl \  
--domain_name="ack.al"
get domain

ackalctl list domain

List this customer's domain name references.

Synopsis


ackalctl \
list domain

Flags

Note No additional flags are used by this command.

Example


ackalctl \
list domain

ackalctl update domain

Update a reference to a domain name.

Synopsis


ackalctl \
update domain

Flags

Note No additional flags are used by this command.

Example


ackalctl \
update domain

ackalctl verify domain

Verify ownership of a domain name.

Synopsis


ackalctl \
verify domain

Flags

Note No additional flags are used by this command.

Example


ackalctl \
verify domain

Location

A Location is a source location where a gRPC health check can be deployed.

ackalctl list location

List the locations that can be used to create health checks.

Synopsis


ackalctl \
list location

Flags

Note No additional flags are used by this command.

Example


ackalctl \
list location

User

An individual user. The user authenticates to Ackal using a 3rd-party OAuth system (e.g. Google) and has a Stripe subscription for Ackal. There are no ackalctl commands for users.