Skip to content

Custom certificates

This page explains how to attach a custom certificate to an API.

Custom certificate diagram

Introduction

This guide provides a concise overview of how custom certificates can be attached to an API (microservice) to secure the connection in a Kubernetes cluster.

Connecting a custom certificate to an API requires two steps:

ServersTransport CRD

In the first step, you have to create the ServersTransport CRD.
ServersTransport allows configuring the transport between the Traefik Hub agent and your Services.

The referenced ServersTransport CRD must be defined in the same Kubernetes Service namespace.

Reference

Field Description
serverName ServerName used to contact the server.
insecureSkipVerify Controls whether the server's certificate chain and host name is verified.
rootCAsSecrets Defines the set of root certificate authorities to use when verifying server certificates. The secret must contain a certificate under either a tls.ca or a ca.crt key.
certificatesSecrets Certificates to present to the server for mTLS.
maxIdleConnsPerHost Controls the maximum idle (keep-alive) connections to keep per-host. If zero, defaultMaxIdleConnsPerHost is used.
forwardingTimeouts Timeouts for requests forwarded to the servers.
dialTimeout The amount of time to wait until a connection to a server can be established. If zero, no timeout exists.
responseHeaderTimeout The amount of time to wait for a server's response headers after fully writing the request (including its body, if any). If zero, no timeout exists.
idleConnTimeout The maximum amount of time an idle (keep-alive) connection will remain idle before closing itself. If zero, no timeout exists.
peerCertURI URI used to match against SAN URIs during the server's certificate verification.
disableHTTP2 Disables HTTP/2 for connections with servers.
spiffe The SPIFFE configuration.
ids Defines the allowed SPIFFE IDs (takes precedence over the SPIFFE TrustDomain).
trustDomain Defines the allowed SPIFFE trust domain.

The CA secret must contain a base64 encoded certificate under either a tls.ca or a ca.crt key.

Example

---
apiVersion: traefik.io/v1alpha1
kind: ServersTransport
metadata:
  name: demo-api-transport
  namespace: apps
spec:
  serverName: gateway.domain.tld
  insecureSkipVerify: true

Service

In the second step, you need to add the traefik.ingress.kubernetes.io/service.serverstransport annotation to the Service definition of the API.

The syntax of the annotation is important!
You have to reference the namespace and the name of your ServersTransport CRD.

Example

---
apiVersion: v1
kind: Service
metadata:
  name: api-demo-svc
  namespace: apps
  annotations:
    traefik.ingress.kubernetes.io/service.serverstransport: apps-demo-api-transport@kubernetescrd
  labels:
    app: api-demo
spec:
  type: ClusterIP
  ports:
  - port: 443
    name: https
  selector:
    app: api-demo

What's next