> For the complete documentation index, see [llms.txt](https://docs-v3.toucantoco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-v3.toucantoco.com/self-hosted-toucan/configuration/https.md).

# Configure HTTPS

## External traffic

### Overview

![External Traffic](/files/zXWSLgNW8F3mfIoKZtGq)

You have one ingress to secure:

* The main entrypoint `nginx` (for the example, we assume the address `app.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:

{% code title="yaml: values.override.yaml" %}

```yaml
global:
  hostname: 'app.example.com'

canopee:
  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., `app.example.com-tls`
    tls: false
    extraHosts: []
      # - name: app.example.com
      #   path: /#
    extraPaths: []
      # - path: /*
      #   backend:
      #     serviceName: ssl-redirect
      #     servicePort: use-annotation
    extraTls: []
      # - hosts:
      #     - app.example.com
      #   secretName: app.example.com-tls
    secrets: []
      # - name: app.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: /
```

{% endcode %}

### Using cert-manager

#### Configuring the Issuer

Check the official documentation: [cert-manager - Issuer Configuration](https://cert-manager.io/docs/configuration/).

{% tabs %}
{% tab title="ACME DNS-01" %}
{% code title="yaml: issuer.yaml" overflow="wrap" %}

```yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: example-issuer
  namespace: cert-manager
spec:
  acme:
    email: notification@example.com
    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
```

{% endcode %}

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

{% tab title="ACME HTTP01" %}
{% code title="yaml: issuer.yaml" overflow="wrap" %}

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

{% endcode %}

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.
{% endtab %}

{% tab title="Self-signed CA" %}
If you don't have a CA ready, you can generate one:

{% code title="yaml: ca.yaml" overflow="wrap" %}

```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
```

{% endcode %}

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

{% code title="yaml: ca-key-pair-secret.yaml" overflow="wrap" %}

```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-----
```

{% endcode %}

{% hint style="info" %}
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 `Certificate`s under the `ca.crt` key. If you fail to provide a complete chain, it might not be possible for consumers of issued `Certificate`s to verify whether they're trusted.
{% endhint %}

Now, deploy the issuer:

{% code title="yaml: issuer.yaml" overflow="wrap" %}

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

{% endcode %}
{% endtab %}
{% endtabs %}

#### Using the Issuer

You can set the parameters as follows:

{% code title="yaml: values.override.yaml" %}

```yaml
global:
  hostname: 'app.example.com'

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

{% endcode %}

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

### Manually

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

{% code title="yaml: tls-secret.yaml" overflow="wrap" %}

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: app.example.com-tls
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
```

{% endcode %}

And set the values:

{% code title="yaml: values.override.yaml" %}

```yaml
global:
  hostname: 'app.example.com'

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

{% endcode %}

{% hint style="info" %}
We do not recommend setting the certificate and private key in the `values.override.yaml` file if you plan to do GitOps in the future.

Prefer using a secret manager like [external-secrets](https://external-secrets.io/latest/) or [sealed-secrets](https://github.com/bitnami-labs/sealed-secrets).
{% endhint %}

## 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.

{% hint style="info" %}
**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.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs-v3.toucantoco.com/self-hosted-toucan/configuration/https.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.