Use AIStore

TLS certificate management via CLI

View as Markdown

Table of Contents

HTTPS deployment implies (and requires) that each AIS node has a valid TLS (a.k.a. X.509) certificate.

The latter has a number of interesting properties ultimately intended to authenticate clients (users) to servers (AIS nodes). And vice versa.

In addition, TLS certificates tend to expire from time to time. In fact, each TLS certificate has expiration date with the standard-defined maximum being 13 months (397 days).

Some sources claim 398 days but the (much) larger point remains: TLS certificates do expire. Which means, they must be periodically updated and timely reloaded.

Starting v3.24, AIStore:

  • tracks certificate expiration times;
  • automatically - upon update - reloads updated certificates;
  • raises associated alerts.

A node may have more than one certificate configured. Each is tracked, reloaded, and alerted on independently; the commands below operate on all of them.

ais tls command

1$ ais tls --help
2NAME:
3   ais tls - Load or reload (an updated) TLS certificate; display information about currently deployed certificates
4
5USAGE:
6   ais tls command [arguments...] [command options]
7
8COMMANDS:
9   show                   Show TLS certificate's version, issuer's common name, from/to validity bounds
10   load-certificate       Load TLS certificates (all configured certificates, on the selected node or cluster-wide)
11   validate-certificates  Check that all TLS certificates are identical
12
13OPTIONS:
14   --help, -h  show help

Cert alerts

Associated alerts are listed below but first - an example:

1$ ais show cluster
2
3PROXY            MEM AVAIL  LOAD AVERAGE    UPTIME      STATUS  ALERT
4p[KKFpNjqo][P]   127.77GiB  [5.2 7.2 3.1]   108h30m40s  online  **tls-cert-will-soon-expire**
5...
6
7TARGET           MEM AVAIL  CAP USED(%)     CAP AVAIL   LOAD AVERAGE    UPTIME      STATUS  ALERT
8t[pDztYhhb]      98.02GiB   16%             960.824GiB  [9.1 13.4 8.3]  108h30m1s  online  **tls-cert-will-soon-expire**
9...
10...

Overall, there are currently 3 (three) related alerts:

alertcomment
tls-cert-will-soon-expirea warning that X.509 cert will expire in less than 3 days
tls-cert-expiredX.509 expired (red alert, as the name implies)
tls-cert-invalide.g., invalid PEM format; further details at OpenSSL: X.509 errors

The alerts above are node-level: when a node has multiple certificates, an alert is raised if any of them is in the corresponding state, and is cleared only when none of them is. Use ais show tls (below) to tell which certificate is at fault.

Show TLS certificate

The command has an optional NODE argument - press <TAB-TAB> to select.

Otherwise, simply run:

1$ ais show tls
2
3PROPERTY                 VALUE
4public-key-algorithm     RSA
5serial-number            55543812950694702162300597243874591179118407338
6signature-algorithm      SHA256-RSA
7valid                    from 2024-08-26 18:18:12 to 2025-08-26 18:18:12
8version                  3
9issued-by (CN)           localhost

When a node has more than one certificate configured, the additional certificate’s properties are shown under a corresponding prefix (e.g., pub.valid); unprefixed properties always refer to the node’s default certificate.

Load TLS certificate

By default, all nodes in the cluster will (unconditionally) reload X.509 certificates from the respective configured locations:

1$ ais tls load-certificate
2
3Done: all nodes.

Each targeted node reloads all of its configured certificates; if any of them fails to load, the command reports the failure and the remaining certificates are still reloaded.

But you can also choose any specific node, and ask it to reload. See ais tls load-certificate --help for details.

If aistore is deployed with authentication (enabled), reloading certificates will require administrative permissions.

See ais config cluster command and related auth.client_auth_required knob.

Further references