Skip to content

Installing with the GitOps endpoint

GitOps practices are a set of workflows and practices that make Git the source of truth for infrastructure configuration management.

Kubernetes only

For now, Traefik Enterprise can be only be installed using GitOps practices on Kubernetes.

Requirements

  • Kubernetes version 1.23 or greater

Installation

To install Traefik Enterprise without the teectl CLI, an HTTP request can be made to generate the required installation manifests, which can then be applied directly to a Kubernetes cluster.

First, your Traefik Enterprise license needs to be specified in a Kubernetes Secret, in the namespace in which you plan to install Traefik Enteprise.

kubectl create namespace traefikee
kubectl create secret generic $CLUSTERNAME-license --from-literal=license="$TRAEFIKEE_LICENSE" -n traefikee

As a convenience, a sample declarative file that can be used with kubectl apply has been provided below:

apiVersion: v1
kind: Namespace
metadata:
  name: traefikee
  namespace: traefikee 
---
apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: default-license
  namespace: traefikee
stringData:
  license: myLicenseString

The next step is to create a ConfigMap containing your Traefik Enterprise static configuration. Traefik Enterprise will watch this configuration and automatically update all of its proxies whenever the ConfigMap's data is edited.

kubectl create configmap --from-file=static.yaml $CLUSTERNAME-static-config -n traefikee

As a convenience, a sample declarative file that can be used with kubectl apply has been provided below:

apiVersion: v1
kind: ConfigMap
metadata:
  namespace: traefikee
  name: default-static-config
data: 
  static.yaml: |
    entryPoints:
      http:
        address: ":80"
      https:
        address: ":443"

    providers:
      kubernetesCRD: {}

    api:
      dashboard: true

Now that your license has been applied and your static configuration is in a ConfigMap, you can query the installer service to generate an installation manifest, which you should review and make any changes that are needed:

curl "https://install.enterprise.traefik.io/v2.12" --output manifest.yaml

Once you have reviewed the manifest, the next step is to apply it using `kubectl`:

kubectl apply -f manifest.yaml

The installation service supports multiple options to customize your installation (namespace, cluster name, etc.).

Custom Installation Parameters

Here are the options that can be specified using query parameters to customize the generated install manifest:

  • cluster string (default: default) : The cluster name
  • namespace string (default: traefikee) : The namespace in which to install
  • clusterdomain string (default: cluster.local) : The cluster domain (required for service mesh)
  • controllers integer (default: 1) : The number of controllers
  • proxies integer (default: 2) : The number of proxies
  • mesh boolean (default: false) : Enable service mesh
  • kubedns boolean (default: false) : The cluster has KubeDNS installed
  • withoutcrds boolean (default: false) : Do not output the CRD part of the manifest
  • withoutresources boolean (default: false) : Do not output the Resources part of the manifest
  • staticconfig string (default: static.yaml) : The name of the static configuration file in the ConfigMap
  • loglevel string (default: "") : The controller and proxies log level
  • logformat string (default: "") : The controller and proxies log format
  • logfilepath string (default: "") : The controller and proxies log filepath

The following command gets an installation manifest that has service mesh enabled, for a cluster that uses KubeDNS, and will install a cluster named staging in the traefikee-staging namespace:

kubectl apply -f "https://install.enterprise.traefik.io/v2.12?cluster=staging&namespace=traefikee-staging&mesh&kubedns"

Using a TOML static configuration instead of YAML

If you use a TOML-formatted configuration, you need to specify the staticconfig option with the file name, including the TOML extension.

Custom cluster name

The names for the license Secret and ConfigMap used to hold the static configuration are dependent on the cluster name, and should be formatted like such: ${CLUSTERNAME}-license for the license secret and ${CLUSTERNAME}-static-config for the ConfigMap that holds the static configuration.

Two-step Install to Split CRDs and Resources

By using the withoutcrds and withoutresources options, you can split your installation into two steps, in order to manage them separately and avoid deleting the CRDs by accident after a blue/green deployment.

Remote static configuration management

If you wish to use teectl to deploy or update your static configuration, instead of letting Traefik Enterprise watch it automatically from a ConfigMap, you can do so by removing the following lines:

        ...
        - name: staticconfig
          mountPath: /var/run/traefikee/config
        ...
        - "--configFile=/var/run/traefikee/config/static.yaml"
        ...
    - name: staticconfig
      configMap:
        name: default-static-config
    ...

Remote Access Through teectl

Once your cluster is ready, if you want to operate the cluster remotely using the teectl tool, you will need to generate credentials from your cluster using traefikee generate credentials on one of your controllers and use teectl to import the cluster credentials.

kubectl exec -n traefikee default-controller-0 -- /traefikee generate credentials --kubernetes.kubeconfig="${KUBECONFIG}"  --cluster=default > config.yaml
teectl cluster import --file="config.yaml"

You can now use teectl to operate your cluster.

teectl get nodes
ID                         NAME                            STATUS  ROLE
3l5xt87fkc2ztlqlkwcpavuev  default-proxy-6f488c84c5-cx9wj  Ready   Proxy / Ingress
52sje29l1zreu1h319vabtzmx  default-controller-1            Ready   Controller
c5j53krue2avv77ajr8h5bcoz  default-controller-0            Ready   Controller (Leader)
yjtz8kvnsgmqmuycup69vx180  default-proxy-6f488c84c5-2zwb7  Ready   Proxy / Ingress
yo4cycxshnuazwvmrfjtowugw  default-proxy-6f488c84c5-b2c9d  Ready   Proxy / Ingress
yqz838gxifzoh0czugxju2r4p  default-controller-2            Ready   Controller

License Monitoring

When a Traefik Enterprise controller starts for the first time, it checks the license validity.

If the license is valid, another check is done once every 24 hours.

If the controller can't communicate with the license server, a 72-day grace period starts to recover from this situation.

Once the grace period is over, the controller stops updating the proxies configuration.

Please look at the FAQ to know how to implement the license monitoring.