Custom Certificates

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

---

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:

• Creating a ServersTransport CRD.
• Adding an annotation to the Kubernetes Service of the API.

---

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.

info

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

Example

YAML

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.

warning

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

Example

YAML

apiVersion: v1
kind: Service
metadata:
  name: api-demo-svc
  namespace: apps
  annotations:
    # "apps" is the namespace and "demo-api-transport" the name of ServersTransport CR, combined with a "-".
    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