⚙️Configure HTTPS

External traffic

Overview

External Traffic

You have one ingress to secure:

• The main entrypoint nginx (for the example, we assume the address toucan.example.com)

This guide assumes you have a DNS entry pointing to the IP address of the Load Balancer where you're running Toucan.

This guide also assume full understanding of TLS and how to configure it.

Parameters

Here's the location of the parameters you need to configure:

yaml: values.override.yaml

global:
  hostname: 'toucan.example.com'

canopee:
  # Gateway API
  httpRoute:
    enabled: false
    annotations: {}
    hostnames: ['{{ .Values.global.hostname }}']
    parentRefs: []
    matches:
      - path:
          type: PathPrefix
          value: /api
    timeouts: {}
    filters: []
    extraRules: []

    ## Add route for tucana
    tucana:
      enabled: true
      matches:
        - path:
            type: PathPrefix
            value: /
      timeouts: {}
      filters: []

  # Ingress API
  ingress:
    enabled: true
    selfSigned: false
    pathType: ImplementationSpecific
    path: /api
    annotations: {}
    hostname: '' # optional, this will be set to `global.hostname`
    ingressClassName: 'nginx'
    # By setting tls to true, the ingress will fetch a secret named `<host>-tls`, i.e., `toucan.example.com-tls`
    tls: false
    extraHosts: []
      # - name: toucan.example.com
      #   path: /#
    extraPaths: []
      # - path: /*
      #   backend:
      #     serviceName: ssl-redirect
      #     servicePort: use-annotation
    extraTls: []
      # - hosts:
      #     - toucan.example.com
      #   secretName: toucan.example.com-tls
    secrets: []
      # - name: toucan.example.com-tls
      #   key: |-
      #     -----BEGIN RSA PRIVATE KEY-----
      #     ...
      #     -----END RSA PRIVATE KEY-----
      #   certificate: |-
      #     -----BEGIN CERTIFICATE-----
      #     ...
      #     -----END CERTIFICATE-----
    extraRules: []
      # See: https://kubernetes.io/docs/concepts/services-networking/ingress/#ingress-rules

    tucana:
      enabled: true
      pathType: ImplementationSpecific
      path: /

Using cert-manager

Configuring the Issuer

Check the official documentation: cert-manager - Issuer Configuration.

ACME DNS-01

yaml: issuer.yaml

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: example-issuer
  namespace: cert-manager
spec:
  acme:
    email: [e-mail]
    server: https://acme-v02.api.letsencrypt.org/directory
    preferredChain: 'ISRG Root X1'
    privateKeySecretRef:
      name: example-issuer-account-key
    solvers:
      - dns01:
          # Use the appropriate Cloud DNS solver
          # See the list at: https://cert-manager.io/docs/configuration/acme/dns01/
          cloudDNS:
            project: $PROJECT_ID
            serviceAccountSecretRef:
              name: clouddns-dns01-solver-svc-acct
              key: key.json

Each time you deploy a new Certificate, the solver will try to create a DNS record with the name _acme-challenge.<host>.

ACME HTTP01

yaml: issuer.yaml

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: example-issuer
spec:
  acme:
    email: [e-mail]
    server: https://acme-v02.api.letsencrypt.org/directory
    preferredChain: 'ISRG Root X1'
    privateKeySecretRef:
      name: example-issuer-account-key
    solvers:
      - http01:
          ingress:
            ingressClassName: nginx

Each time you deploy a new Certificate, the solver will try to create an ingress using the ingressClassName you set in the http01 solver.

Be sure to open port 80 on the Load Balancer and firewall so that the ACME server can reach your ingress to fetch the challenge.

Self-signed CA

If you don't have a CA ready, you can generate one:

yaml: ca.yaml

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: selfsigned-issuer
  namespace: cert-manager
spec:
  selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: root-ca
  namespace: cert-manager
spec:
  isCA: true
  duration: 43800h # 5 year
  renewBefore: 720h # 30 days before expiry
  subject:
    organizations: [My Organization]
    countries: [FR]
    organizationalUnits: [IT]
    localities: [Paris]
  commonName: Root CA
  isserRef:
    name: selfsigned-issuer
    kind: Issuer
  secretName: ca-key-pair

If you are using an existing CA, deploy your CA certificate as a Secret:

yaml: ca-key-pair-secret.yaml

apiVersion: v1
kind: Secret
metadata:
  name: ca-key-pair
stringData:
  ca.crt: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
  ca.key: |
    -----BEGIN RSA PRIVATE KEY-----
    ...
    -----END RSA PRIVATE KEY-----

Note: If your issuer represents an intermediate, ensure that tls.crt contains the issuer's full chain in the correct order: issuer -> intermediate(s) -> root. The root (self-signed) CA certificate is optional, but adding it will ensure that the correct CA certificate is stored in the secrets for issued Certificates under the ca.crt key. If you fail to provide a complete chain, it might not be possible for consumers of issued Certificates to verify whether they're trusted.

Now, deploy the issuer:

yaml: issuer.yaml

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: example-issuer
  namespace: cert-manager
spec:
  ca:
    secretName: ca-key-pair

Using the Issuer

Gateway API

If you are using Gateway API, you should have configured the Gateway. Add a new listener to the gateway and specify the certificate issuer in the annotations:

yaml: /work/gateway/gateway.yaml

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: eg
  namespace: envoy-gateway-system
  annotations:
    cert-manager.io/cluster-issuer: example-issuer
spec:
  gatewayClassName: envoy-gateway
  # ...
  listeners:
    # ...
    - name: toucan
      protocol: HTTPS
      port: 443
      hostname: toucan.example.com
      tls:
        mode: Terminate
        certificateRefs:
          - name: toucan.example.com-tls
      allowedRoutes:
        namespaces:
          from: Selector
          selector:
            matchLabels:
              kubernetes.io/metadata.name: <namespace>

You can set the parameters as follows:

yaml: values.override.yaml

global:
  hostname: 'toucan.example.com'

canopee:
  httpRoute:
    enabled: true
    parentRefs:
      - name: eg
        namespace: envoy-gateway-system

Ingress API

You can set the parameters as follows:

yaml: values.override.yaml

global:
  hostname: 'toucan.example.com'

canopee:
  ingress:
    enabled: true
    ingressClassName: nginx
    annotations:
      cert-manager.io/issuer: example-issuer
    tls: true

This will automatically generate a certificate and secret named toucan.example.com-tls, and configure the ingress to use the certificate issued by the Issuer named test-issuer.

Manually

Gateway API

If you have a certificate and private key ready, you can deploy it as a Secret:

yaml: /work/gateway/tls-secret.yaml

apiVersion: v1
kind: Secret
metadata:
  name: toucan.example.com-tls
  # If using Gateway API, you must specify the namespace of the Gateway
  namespace: envoy-gateway-system
stringData:
  tls.crt: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
  tls.key: |
    -----BEGIN RSA PRIVATE KEY-----
    ...
    -----END RSA PRIVATE KEY-----
  ca.crt: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
type: kubernetes.io/tls

If you are using Gateway API, you should have configured the Gateway. Add a new listener to the gateway and specify the certificate issuer in the annotations:

yaml: /work/gateway/gateway.yaml

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: eg
  namespace: envoy-gateway-system
  annotations:
    cert-manager.io/cluster-issuer: example-issuer
spec:
  gatewayClassName: envoy-gateway
  # ...
  listeners:
    # ...
    - name: toucan
      protocol: HTTPS
      port: 443
      hostname: toucan.example.com
      tls:
        mode: Terminate
        certificateRefs:
          - name: toucan.example.com-tls
      allowedRoutes:
        namespaces:
          from: Selector
          selector:
            matchLabels:
              kubernetes.io/metadata.name: <namespace>

You can set the parameters as follows:

yaml: values.override.yaml

global:
  hostname: 'toucan.example.com'

canopee:
  httpRoute:
    enabled: true
    parentRefs:
      - name: eg
        namespace: envoy-gateway-system

Ingress API

If you have a certificate and private key ready, you can deploy it as a Secret:

yaml: tls-secret.yaml

apiVersion: v1
kind: Secret
metadata:
  name: toucan.example.com-tls
  # Else, if using Ingress API, you must specify the namespace of the Ingress (where Toucan is deployed)
  namespace: <namespace>
stringData:
  tls.crt: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
  tls.key: |
    -----BEGIN RSA PRIVATE KEY-----
    ...
    -----END RSA PRIVATE KEY-----
  ca.crt: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
type: kubernetes.io/tls

You can set the parameters as follows:

yaml: values.override.yaml

global:
  hostname: 'toucan.example.com'

canopee:
  ingress:
    enabled: true
    ingressClassName: nginx
    tls: true
    extraTls:
      - hosts:
          - toucan.example.com
        secretName: toucan.example.com-tls

Internal traffic

By default, TLS or mTLS is enabled for all services using self-signed certificates.

This configuration is already highly secure, as the self-signed Certificate Authority (CA) remains entirely within the Kubernetes environment and is never exposed externally.

That said, you may choose to use your own Public Key Infrastructure (PKI) to facilitate more flexible and centralized trust management.

Note: At the moment of writing, we are unable to offer you a proper way to configure TLS or mTLS on the client. This feature is planned for a future release. Thank you for your patience.