File system certificate configuration reference

This topic provides reference information for the file system certificate configuration entry. The file system certificate is a more secure alternative to the inline certificate configuration entry when using Consul API Gateway on VMs because it references a local filepath instead of including sensitive information in the configuration entry itself. File system certificates also include a file system watch that implements certificate and key changes without restarting the gateway.

Consul on Kubernetes deployments that use consul-k8s Helm chart v1.5.0 or later use file system certificates without additional configuration. To learn about configuring certificates for Kubernetes environments, refer to Gateway Resource Configuration.

Configuration model

The following list outlines field hierarchy, language-specific data types, and requirements in a file-system-certificate configuration entry. Click on a property name to view additional details, including default values.

• Kind: string | must be set to "file-system-certificate"
• Name: string | no default
• Namespace: string | no default EnterpriseEnterprise
• Partition: string | no default EnterpriseEnterprise
• Meta: map | no default
• Certificate: string | no default
• PrivateKey: string | no default

Complete configuration

When every field is defined, a file-system-certificate configuration entry has the following form:

Kind = "file-system-certificate"
Name = "<name of certificate>"
Namespace = "ns"
Partition = "default"
Meta = {
    "<key>" = "<value>"
}

Certificate = "<filepath/to/public/certificate>"
PrivateKey = "<filepath/to/private/key>"

{
    "Kind": "file-system-certificate",
    "Name": "<name of certificate>",
    "Namespace": "ns",
    "Partition": "default",
    "Meta": {
        "key": "value"
    },
    "Certificate": "<filepath/to/public/certificate>",
    "PrivateKey": "<filepath/to/private/key>"
}

Specification

Kind

Specifies the type of configuration entry to implement.

Values

• Default: None
• This field is required.
• Data type: string that must equal "file-system-certificate"

Name

Specifies a name for the configuration entry. The name is metadata that you can use to reference the configuration entry when performing Consul operations, such as applying a configuration entry to a specific cluster.

Values

• Default: None
• This field is required.
• Data type: string

Namespace EnterpriseEnterprise

Specifies the Enterprise namespace to apply to the configuration entry.

Values

• Default: "default" in Enterprise
• Data type: string

Partition EnterpriseEnterprise

Specifies the Enterprise admin partition to apply to the configuration entry.

Values

• Default: "default" in Enterprise
• Data type: string

Meta

Specifies an arbitrary set of key-value pairs to associate with the gateway.

Values

• Default: None
• Data type: map containing one or more keys and string values.

Certificate

Specifies the path to a file that contains a public certificate to use for TLS. This filepath must be accessible to the API gateway proxy at runtime.

Values

• Default: none
• This field is required.
• Data type: string value of the filepath to a public certificate

PrivateKey

Specifies the path to a file that contains a private key to use for TLS. This filepath must be accessible to the API gateway proxy at runtime.

Values

• Default: none
• This field is required.
• Data type: string value of the filepath to a private key

Examples

The following example demonstrates a file system certificate configuration.

Kind                     = "file-system-certificate"
Name                     = "tls-certificate"
Certificate              = "/opt/consul/tls/api-gateway.crt"
PrivateKey               = "/opt/consul/tls/api-gateway.key"

{
  "Kind": "file-system-certificate",
  "Name": "tls-certificate",
    "Certificate": "opt/consul/tls/api-gateway.crt",
    "PrivateKey": "/opt/consul/tls/api-gateway.key"
}