ACME / Let's Encrypt Operations¶

TraefikEE offers a flexible account and certificate management system for ACME using either traefikee or traefikeectl command-line tool. Those tools allow you to import an existing account or to create a new one.

You can have multiple ACME accounts on a cluster, but for now, only one can be active at a time. This means that certificates generated with other accounts than the active one will not be renewed.

Installing traefikeectl

In order to perform those operations with traefikeectl, you will need to install it.

Creating ACME Accounts¶

You can let TraefikEE create a new ACME account for you by using the commands traefikee acme-add-account or traefikeectl acme-add-account:

With traefikeectl

traefikeectl acme-add-account \
    --name="myaccount" \
    --email="[email protected]" \
    --caserver="https://ca.server.com"

Expected output

Connecting to TraefikEE Control API...ok
Adding a new ACME account...ok
✔ Account "myaccount" has been added to cluster "traefikee"

With traefikee

traefikee acme-add-account \
    --name="myaccount" \
    --email="[email protected]" \
    --caserver="https://ca.server.com"

Expected output

Account "myaccount" has been added to cluster "traefikee"

This will add an account which will be registered once a deployment is made.

When running acme-list-accounts, you should now be able to see your new ACME account.

With traefikeectl

traefikeectl acme-list-accounts

With traefikee

traefikee acme-list-accounts

Expected output

Email           Name        CA Server               Current
-----           ----        ---------               -------
[email protected]     myaccount   https://ca.server.com

In order to use it as your cluster's ACME account, you will now need to use the acme-use-account command.

TraefikEE Premium ACME accounts

If you have subscribed to premium ACME accounts, your cluster comes with two accounts (Production and Staging) already built-in. You do not have to manually create or add these accounts.

Importing ACME Accounts¶

In order to import an existing ACME account to your TraefikEE cluster, use the commands traefikee acme-add-account or traefikeectl acme-add-account, and specify the following arguments:

With traefikeectl

traefikeectl acme-add-account \
    --name="myaccount" \
    --email="[email protected]" \
    --caserver="https://ca.server.com" \
    --privatekey="encodedkey" \
    --uri="https://ca.server.com/accountid"

Expected output

Connecting to TraefikEE Control API...ok
Adding a new ACME account...ok
✔ Account "myaccount" has been added to cluster "traefikee"

With traefikee

traefikee acme-add-account \
    --name="myaccount" \
    --email="[email protected]" \
    --caserver="https://ca.server.com" \
    --privatekey="encodedkey" \
    --uri="https://ca.server.com/accountid"

Expected output

Account "myaccount" has been added to cluster "traefikee"

It's also possible to import an account from a TraefikEE backup's account.json file:

From a backup

traefikeectl acme-add-account --backupaccount="./backup/acme/myaccount/account.json"

Expected output

Forwarding TraefikEE Control API port...ok
Connecting to TraefikEE Control API...ok
Adding a new ACME account...ok
✔ Account "myaccount" has been added to cluster "traefikee"

How to get the account.json file

In order to get the account.json file from a TraefikEE backup, simply extract it and it should be located in acme/<the_account_name>/account.json.

When running acme-list-accounts, you should now be able to see your new ACME account.

With traefikeectl

traefikeectl acme-list-accounts

With traefikee

traefikee acme-list-accounts

Expected output

Email           Name        CA Server               Current
-----           ----        ---------               -------
[email protected]     myaccount   https://ca.server.com

In order to use it as your cluster's ACME account, you will now need to use the acme-use-account command.

Setting the Current ACME Account¶

In order to use an ACME account for generating and renewing your cluster's certificates, you need to set it as the current ACME account. This can be done using the commands traefikeectl acme-use-account or traefikee acme-use-account, like such:

With traefikeectl

traefikeectl acme-use-account --name="myaccount"

With traefikee

traefikee traefikeectl acme-use-account --name="myaccount"

One time operation

You can only run this command once per installed cluster, for now.

When running a acme-list-accounts command, your account should be shown as the selected account:

With traefikeectl

traefikeectl acme-list-accounts

With traefikee

traefikee acme-list-accounts

Expected output

Email           Name        CA Server               Current
-----           ----        ---------               -------
[email protected]     myaccount   https://ca.server.com   YES

Importing ACME Certificates¶

In order to import an existing ACME certificate to your TraefikEE cluster, use the commands traefikee acme-add-certificate or traefikeectl acme-add-certificate, and specify the following arguments:

With traefikeectl and PEM files

traefikeectl acme-add-certificate \
    --certfile="./cert.pem" \
    --keyfile="./key.pem" \
    --accountname="myaccount"

Expected output

Forwarding TraefikEE Control API port...ok
Checking configuration...ok
Loading ACME certificate and key...ok
Connecting to TraefikEE Control API...ok
Looking for account "myaccount" in cluster "traefikee"...ok
Adding a new ACME certificate...ok
✔ Certificate has been successfully linked to account "myaccount"

With traefikeectl and TraefikEE backup files

traefikeectl acme-add-certificate \
    --backupcert="./cec5xxxcvkovbv6kbqiqjnqgnb1.json" \
    --accountname="myaccount"

Expected output

Forwarding TraefikEE Control API port...ok
Checking configuration...ok
Loading ACME certificate and key...ok
Connecting to TraefikEE Control API...ok
Looking for account "myaccount" in cluster "traefikee"...ok
Adding a new ACME certificate...ok
✔ Certificate has been successfully linked to account "myaccount"

With traefikee and PEM files

traefikee acme-add-certificate \
    --certfile="./cert.pem" \
    --keyfile="./key.pem" \
    --accountname="myaccount"

Expected output

Certificate successfully linked to the "myaccount" ACME account

With traefikee and TraefikEE backup files

traefikee acme-add-certificate \
    --backupcert="./cec5xxxcvkovbv6kbqiqjnqgnb1.json" \
    --accountname="myaccount"

Expected output

Certificate successfully linked to the "myaccount" ACME account

Pass the content of certificates through the command-line

If you are in an environment where you can't write the certificates on the filesystem, it might make sense for you to pass the content of the PEM-encoded or JSON-encoded files representing your certificates. You can then simply pass the content of the files instead of their path, to the --certfile, --keyfile and --backupcert options.