Certificate Setup

Overview

Certificate setup for ingress using TrueNAS and TrueCharts.

Assumptions

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

SettingValueDescription
Application Namecert-managerName 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.

SettingValueDescription
Token Nameexample-api-tokenChoose a name to identify the token.
PermissionsZone - DNS - EditGrant edit permissions for zone DNS.
Zone ResourcesInclude - Specific - example.comOnly include the zone that will utilize the token.

Cloudflare API token creation tool.

Continue to summary and review the configuration, select Create Token.

When presented, copy the generated Cloudflare API token.

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

SettingValueDescription
Application NameclusterissuerName for the application.
Version Number#.#.#Version to use, latest by default.

App Configuration

SettingValueDescription
ACME Issuer
NamecertName for the issuer, will be used when configuring applications to use ClusterIssuer.
Type or DNS-ProviderCloudflareSelect the DNS provider for DNS ACME challenges. Same provider API token created for.
ServerLetsencrypt-ProductionACME server to use for getting certificates.
Email[email protected]Public email for certificate issuing.
Cloudflare API KeyAvoid API keys, use a token whenever possible.
Cloudflare API TokenAPI-TOKENAPI token generated with DNS edit permissions for the domain.
Self Signed Issuer
EnabledfalseKeep 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.

SettingValueDescription
Cert-Manager ClusterIssuercertConfigured name of the ClusterIssuer ACME issuer.

LLDAP ingress configuration with ‘cert’ ClusterIssuer.

References

1 2 3 4