Certificate Setup
Overview
Certificate setup for ingress using TrueNAS and TrueCharts.
Assumptions
TrueNAS Scale setup completed.
TrueCharts catalog setup completed.
Logged in as administrative user.
Install Cert Manager
Navigate to the Applications page in the TrueNAS Scale dashboard, Apps on the main navigation.
Switch to the Available Applications tab in the Applications page.
Using the search tool, find the cert-manager application. Verify Cert Manager is from the TrueCharts catalog and is on the Operators train.
Select Install to begin configuration and installation of the application. Configuration options not mentioned in this section can be left as default.
Application Name
| Setting | Value | Description |
|---|---|---|
| Application Name | cert-manager | Name for the application. |
| Version Number | #.#.# | Version to use, latest by default. |
Save
Verify you have checked the TrueCharts documentation for Cert Manager and Save. The application will begin installation and deploy. Navigate to the Installed Applications tab to monitor the status.
ACME Challenge
To generate certificates, an ACME challenge needs to be completed. This is required for ClusterIssuer setup. One of the following providers must be used for completing DNS ACME challenges: Cloudflare, Route53, Akamai, or DigitalOcean. Generate an API token with one of these providers to use during ClusterIssuer configuration. Cloudflare will be used in this demonstration.
Cloudflare API Token
Create an API token to interact with a Cloudflare Zone.
Navigate to the My Profile page and select the API Tokens tab.
Select Create Token. Configure the token with permission to edit Zone DNS. Only allow access to the zone resource required.
| Setting | Value | Description |
|---|---|---|
| Token Name | example-api-token | Choose a name to identify the token. |
| Permissions | Zone - DNS - Edit | Grant edit permissions for zone DNS. |
| Zone Resources | Include - Specific - example.com | Only include the zone that will utilize the token. |
Continue to summary and review the configuration, select Create Token.
When presented, copy the generated Cloudflare API token.
Install ClusterIssuer
Navigate to the Applications page in the TrueNAS Scale dashboard, Apps on the main navigation.
Switch to the Available Applications tab in the Applications page.
Using the search tool, find the clusterissuer application. Verify ClusterIssuer is from the TrueCharts catalog and is on the Enterprise train.
Select Install to begin configuration and installation of the application. Configuration options not mentioned in this section can be left as default.
Application Name
| Setting | Value | Description |
|---|---|---|
| Application Name | clusterissuer | Name for the application. |
| Version Number | #.#.# | Version to use, latest by default. |
App Configuration
| Setting | Value | Description |
|---|---|---|
| ACME Issuer | — | — |
| Name | cert | Name for the issuer, will be used when configuring applications to use ClusterIssuer. |
| Type or DNS-Provider | Cloudflare | Select the DNS provider for DNS ACME challenges. Same provider API token created for. |
| Server | Letsencrypt-Production | ACME server to use for getting certificates. |
[email protected] | Public email for certificate issuing. | |
| Cloudflare API Key | | Avoid API keys, use a token whenever possible. |
| Cloudflare API Token | API-TOKEN | API token generated with DNS edit permissions for the domain. |
| Self Signed Issuer | — | — |
| Enabled | false | Keep disabled when using an ACME issuer. |
Save
Verify you have checked the TrueCharts documentation for ClusterIssuer and Save. The application will begin installation and deploy. Navigate to the Installed Applications tab to monitor the status.
The ClusterIssuer app will always be in the STOPPED state on the Applications dashboard. It will not enter the ACTIVE state like other applications.
Ingress
With an ingress proxy server setup, the ClusterIssuer can be used to generate certificates for ingress hostnames. The ClusterIssuer will automatically complete the DNS challenge with the configured provider.
When configuring ingress on an application, specify the configured ACME issuer name.
| Setting | Value | Description |
|---|---|---|
| Cert-Manager ClusterIssuer | cert | Configured name of the ClusterIssuer ACME issuer. |
References
Cloudflare. “Cloudflare API Documentation.” 2024. ↩︎
Let’s Encrypt. “Let’s Encrypt Documentation.” 2024. ↩︎