Installation

How to install and configure the Traefik Hub Agent.

Introduction¶

Before you begin the installation process, it is recommended that you have a basic understanding of Kubernetes.

You should have access to a working Kubernetes cluster, either on a cloud provider or on your own infrastructure.

You will learn the steps required to install a Traefik Hub Agent as a sidecar container using kubectl and Helm.

By the end of this tutorial, you will have a running instance of a Traefik Hub Agent that can be used to manage and route incoming traffic to your APIs.

The Traefik Hub Agent supports any Ingress Controller, see the following examples for Traefik Proxy and NGINX.

Before you begin¶

Before getting started, make sure you have the following:

• Helm installed

Installation¶

1. Generate token¶

Login to your account on Traefik Hub and generate a token.

2. Set environment variables¶

The commands for installing the Hub Agent use variables with the format ${VARIABLE_NAME}.

For this tutorial, you will define and export these in the CLI.

export NAMESPACE=traefik
export DEPLOYMENT=traefik
export HUB_TOKEN=XXX
export HELM_RELEASE=traefik
export HELM_CHART=traefik/traefik
export INGRESS_CONTROLLER=traefik
export SERVICE_ACCOUNT_NAME=traefik
export SERVICE_ACCOUNT_NAMESPACE=traefik

export NAMESPACE=ingress-nginx
export DEPLOYMENT=ingress-nginx-controller
export HUB_TOKEN=XXX
export HELM_RELEASE=ingress-nginx
export HELM_CHART=ingress-nginx/ingress-nginx
export INGRESS_CONTROLLER=nginx
export SERVICE_ACCOUNT_NAME=ingress-nginx
export SERVICE_ACCOUNT_NAMESPACE=ingress-nginx

• NAMESPACE: Namespace of Ingress Controller and the Hub Agent
• DEPLOYMENT: Name of the deployment
• HUB_TOKEN: Your Traefik Hub token
• HELM_RELEASE: Name of the Ingress Controller chart repository
• HELM_CHART Name of the Ingress Controller chart, can be Traefik or NGINX (Community edition)
• INGRESS_CONTROLLER: Name of the Ingress Controller deployment, can be Traefik or NGINX (Community edition)
• SERVICE_ACCOUNT_NAME: Name of the Kubernetes ServiceAccount for the Traefik Hub Agent
• SERVICE_ACCOUNT_NAMESPACE: Namespace of the ServiceAccount for the Hub Agent

3. Add the Helm repository¶

Once you have configured all needed variables, use Helm to initialize the chart repository.

helm repo add traefik https://traefik.github.io/charts
helm repo update

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update

4. Deploy Custom Resources¶

Deploy the CRDs for the Hub Agent.

# Hub Agent CRD
kubectl apply -f "https://hub.traefik.io/install/crd"
kubectl apply -f "https://hub.traefik.io/install/rbac?serviceAccountName=${SERVICE_ACCOUNT_NAME}&serviceAccountNamespace=${SERVICE_ACCOUNT_NAMESPACE}"

5. Install the Ingress Controller¶

In this step, you will use Helm to install the Ingress Controller.

# Install Ingress Controller
helm upgrade --create-namespace --install "${HELM_RELEASE}" "${HELM_CHART}" --namespace "${NAMESPACE}" --values "https://hub.traefik.io/install/helm?token=${HUB_TOKEN}&ic=${INGRESS_CONTROLLER}"

6. Create the admission service¶

Now, you will configure and deploy the admission service for the Hub Agent.

# Expose the admission service (sidecar)
kubectl expose deployment -n "${NAMESPACE}" "${DEPLOYMENT}" --port=443 --target-port=9943 --name admission

# Create mutating webhook
kubectl apply -f "https://hub.traefik.io/install/admission?namespace=${NAMESPACE}&token=${HUB_TOKEN}"

Congratulations, your Hub Agent is installed!

Migration from previous version¶

How-to migrate from the Hub Agent v1.

Please make sure to have your Traefik Hub Agent token by hand! The token is needed to connect to your already configured Hub Agent.

First remove the old Hub Agent, adjust the example below to match your setup.

The example below assumes that the old Hub Agent is deployed into the hub-agent namespace.

1. Set environment variables¶

The commands for migrating the Hub Agent use variables with the format ${VARIABLE_NAME}.

# Old Hub Agent
export HUB_NAMESPACE=hub-agent
export HUB_HELM_RELEASE=hub-agent

# Ingress Controller
export NAME=traefik
export NAMESPACE=traefik
export DEPLOYMENT=traefik
export SERVICE_ACCOUNT=traefik
export HELM_RELEASE=traefik
export HELM_CHART=traefik/traefik

2. Remove the old Hub Agent¶

Use Helm to remove the old Agent.

# Remove the Hub Agent
helm uninstall -n "${HUB_NAMESPACE}" "${HUB_HELM_RELEASE}"

3. Update CRDs and RBAC¶

In the next step, update the Custom Resources and Role-based access control (RBAC).

# Update CRDs and RBAC
kubectl apply -f "https://hub.traefik.io/install/crd"
kubectl apply -f "https://hub.traefik.io/install/rbac?serviceAccountName=${SERVICE_ACCOUNT}&serviceAccountNamespace=${NAMESPACE}"

4. Update the Ingress Controller¶

Use Helm to update the Ingress Controller

# Update the Ingress Controller
helm upgrade --create-namespace --install "${HELM_RELEASE}" "${HELM_CHART}" --namespace "${NAMESPACE}" --reuse-values --values "https://hub.traefik.io/install/helm?token=${HUB_TOKEN}&ic=${NAME}"

5. Create the admission service¶

In the next step, you will configure and deploy the admission service for the Hub Agent.

# Expose the admission service (sidecar)
kubectl expose deployment -n "${NAMESPACE}" "${DEPLOYMENT}" --port=443 --target-port=9943 --name admission

# Create mutating webhook
kubectl apply -f "https://hub.traefik.io/install/admission?namespace=${NAMESPACE}&token=${HUB_TOKEN}"