Use

Certificates (internal CA) WIP

Certificates of your own CA for every guest – handed out by the NetBox provisioner or placed by hand. Every app keeps working without them.

Why

Web interfaces get TLS from a reverse proxy with Let’s Encrypt. But some things are not behind a proxy:

• apps you open directly, e.g. the web app of AI-Workstation – today with a self-signed certificate you have to click away;
• connections between services – central logs, metrics – where both sides should know who they talk to (client certificates; public CAs no longer issue those).

An internal CA solves both: your devices trust its root once, every guest gets a certificate from it.

Three ways – every app works with all of them

A guest never depends on the provisioner – it only knows fixed paths, and who put the files there does not matter.

The paths in the guest

Apps with their own TLS use /etc/iac/tls/ when a certificate is there and fall back to their self-signed one otherwise. After a new certificate they reload only the services that need it.

By hand

1. Copy your root certificate (PEM) to /etc/iac/ca/, e.g. /etc/iac/ca/my-root.crt.

2. Create the key and a request in the guest – the key stays there:

   iac-tls csr myhost.intra.example.org 192.168.40.20 > myhost.csr
   

3. Sign myhost.csr with your CA, then install the certificate with its chain:

   iac-tls install < myhost.crt
   update          # once: the root into the trust store, apps switch from self-signed
   

iac-tls install checks that the certificate matches the key and is still valid before it replaces the old one. Renewing is the same steps again before the certificate expires.

With the provisioner

The provisioner holds an intermediate of your CA and signs itself – no CA server, no ACME, no DNS challenge:

1. It asks the node for a request from the guest (iac-tls csr with the names and IPs NetBox has for this VM).
2. It signs only if the names and IPs in the request match that VM in NetBox exactly.
3. It hands the certificate back (iac-tls install). Validity e.g. 30 days, for servers and as a client certificate.
4. It renews after two thirds of the validity, in its normal five-minute run.

The root comes from the config context iac in NetBox and is placed in new guests when they are created, and in existing guests on the next run.

If the provisioner is down for longer than a certificate is valid, certificates expire: the services keep running, clients warn. Guests not in NetBox get no certificate automatically – place it by hand or add them to NetBox.

Create your CA

The root is created once, offline, and stays offline (password manager, USB stick). It signs only the intermediate. Give the root name constraints – only your internal domain and private networks – then even a stolen intermediate cannot issue certificates for other sites, although your devices trust the root.

Then import the root once on your computers and phones.

For app developers

Apps that serve TLS themselves (not behind a reverse proxy) use the helper role iac_tls of iac-core instead of creating a self-signed certificate – see the app reference.

Planned uses

• Web interfaces opened directly (AI-Workstation first).
• Central logs: every guest sends its journal (systemd-journal-upload from Debian) with its client certificate to a log server.