Skip to content

Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.

docs(cert-agent): combined certificate chain output

bernie-g3f69e99ccf8e
diff --git a/docs/documentation/platform/pki/reference/infisical-agent.mdx b/docs/documentation/platform/pki/reference/infisical-agent.mdx
index 760ec951d7..a4bb7d6473 100644
--- a/docs/documentation/platform/pki/reference/infisical-agent.mdx
+++ b/docs/documentation/platform/pki/reference/infisical-agent.mdx
@@ -173,6 +173,7 @@ Each entry in the `certificates` list accepts the following parameters:
| `file-output.chain.path` | Optional | The path to store the certificate chain |
| `file-output.chain.permission` | Optional (defaults to `0600`) | The octal file permissions for the chain file (e.g. `0644`) |
| `file-output.chain.omit-root` | Optional (defaults to `true`) | Whether to exclude the root CA certificate from the written chain |
+| `file-output.combine-certificate-chain` | Optional (defaults to `false`) | Whether to write the certificate followed by its chain to `certificate.path` as a single full-chain file. When `true`, `chain.path` is ignored and `chain.omit-root` still applies. See [Full-chain file for NGINX](#full-chain-file-for-nginx) |
| `lifecycle.renew-before-expiry` | Optional (auto-renewal is disabled if not set) | How long before expiration the agent should renew the certificate (e.g. `14d`). Must be shorter than the certificate's TTL |
| `lifecycle.replace-on-renewals` | Optional (defaults to `false`) | Only valid with `certificate-id`. Whether the agent should deliver the most recent renewal of that certificate instead of the certificate itself |
| `lifecycle.status-check-interval` | Optional (defaults to `10s`) | How frequently the agent checks certificate status and renewal needs |
@@ -352,6 +353,59 @@ certificates:
timeout: 30
```
+### Full-chain file for NGINX
+
+NGINX expects the certificate and its intermediate chain in one file. With `combine-certificate-chain: true`, the agent writes the certificate followed by the chain to `certificate.path` on issuance and on every renewal. No concatenation script is needed.
+
+```yaml
+version: v2
+
+infisical:
+ address: "https://app.infisical.com"
+
+auth:
+ type: "universal-auth"
+ config:
+ client-id: "/etc/infisical/client-id"
+ client-secret: "/etc/infisical/client-secret"
+
+certificates:
+ - application-name: "web-services"
+ profile-name: "web-server"
+ attributes:
+ common-name: "api.example.com"
+ ttl: "30d"
+ lifecycle:
+ renew-before-expiry: "14d"
+ status-check-interval: "6h"
+ file-output:
+ combine-certificate-chain: true
+ private-key:
+ path: "/etc/ssl/private/api.example.com.key"
+ permission: "0600"
+ certificate:
+ path: "/etc/ssl/certs/api.example.com.fullchain.pem"
+ permission: "0644"
+ post-hooks:
+ on-issuance:
+ command: "systemctl reload nginx"
+ timeout: 30
+ on-renewal:
+ command: "systemctl reload nginx"
+ timeout: 30
+```
+
+Configure NGINX with the combined file and the private key:
+
+```nginx
+ssl_certificate /etc/ssl/certs/api.example.com.fullchain.pem;
+ssl_certificate_key /etc/ssl/private/api.example.com.key;
+```
+
+The root CA is left out of the file by default. Set `file-output.chain.omit-root: false` to include it.
+
+On restart, the agent compares the file with the current certificate and chain. It rewrites the file and runs `on-issuance` only when they differ. This happens after the option is turned on for an existing leaf-only file.
+
### Tracking an existing certificate
Instead of issuing a new certificate, the agent can fetch an existing one by setting `certificate-id`. The agent downloads the certificate bundle, writes it to the configured paths, and monitors its status on the configured `status-check-interval`. If the certificate is revoked or expires, the agent runs the `on-failure` hook and stops.