traefik_kubernetes
traefik-kubernetes
Эта роль Ansible устанавливает Traefik как маршрутизатор для Kubernetes в качестве контроллера входящего трафика. За кулисами используется официальный Helm chart. В настоящее время поддерживаются процедуры установки, обновления и удаления развертывания Traefik.
Предоставленные настройки по умолчанию оптимизированы для Kubernetes-кластера, установленного на физические серверы, где Traefik является публичной точкой входа для сервисов Kubernetes. Хотя конфигурацию, конечно, можно настроить так же, как и с любым другим Helm chart, по умолчанию Traefik будет установлен со следующими параметрами:
- Экземпляры Traefik будут развернуты как
DaemonSet
- Подов Traefik используются
hostPort
- Traefik слушает порт
80
на всех интерфейсах хоста для входящих HTTP-запросов - Traefik слушает порт
443
на всех интерфейсах хоста для входящих HTTPS-запросов - Панель управления Traefik включена и не доступна из публичной сети
- TLS-сертификаты предоставляются cert-manager (моя роль Ansible cert-manager-kubernetes может быть использована для установки cert-manager)
Для получения дополнительной информации о настройках Helm chart смотрите ниже.
Версии
Я помечаю каждый релиз и стремлюсь соблюдать семантическое версионирование. Если вы хотите использовать эту роль, я рекомендую проверить последнюю метку. Основная ветка по сути является веткой разработки, а метки обозначают стабильные выпуски. Но в общем я также стараюсь поддерживать основную ветку в хорошем состоянии. Метка 5.0.0+23.0.1
означает, что это релиз 5.0.0
данной роли и используется версия Helm chart 23.0.1
(версия Traefik
, используемая, указана в файле значений [см. ниже]). Если сама роль изменится, X.Y.Z
перед +
увеличится. Если версия графика Traefik изменится, X.Y.Z
после +
также увеличится. Это позволяет помечать исправления ошибок и новые главные версии роли, в то время как она все еще разрабатывается для конкретного релиза Traefik.
Требования
Вам необходимо установить двоичный файл Helm 3 на том хосте, где выполняется ansible-playbook
, или на том хосте, куда вы делегировали плейбуки (например, используя переменную traefik_delegate_to
). Вы можете либо
- использовать ваш любимый менеджер пакетов, если ваша дистрибуция включает
helm
в своём репозитории (например, для Archlinux используйтеsudo pacman -S helm
) - или использовать одну из ролей Ansible
Helm
(например, helm - которая также будет установлена, если вы используете командуansible-galaxy role install -vr requirements.yml
) - или скачать двоичный файл напрямую из релизов Helm и поместить его в директорию
/usr/local/bin/
Также нужен правильно настроенный KUBECONFIG
(по умолчанию находится по адресу ${HOME}/.kube/config
). Обычно, если kubectl
работает с вашим кластером, то с этой точки зрения всё должно быть в порядке.
Кроме того, необходимо установить коллекцию Ansible kubernetes.core
. Это можно сделать, используя файл collections.yml
, включенный в эту роль: ansible-galaxy install -r collections.yml
.
И, конечно, вам нужен кластер Kubernetes ;-)
Изменения
Смотрите CHANGELOG.md
Переменные роли
# Версия Helm chart
traefik_chart_version: "23.2.0"
# Имя релиза Helm
traefik_release_name: "traefik"
# Имя репозитория Helm
traefik_repo_name: "traefik"
# Имя Helm chart
traefik_chart_name: "{{ traefik_repo_name }}/{{ traefik_release_name }}"
# URL Helm chart
traefik_chart_url: "https://helm.traefik.io/traefik"
# Пространство имен Kubernetes, в котором должны быть установлены ресурсы Traefik
traefik_namespace: "traefik"
# Директория, содержащая файл значений Helm chart. Если вы укажете эту
# переменную, Ansible попытается найти файл с именем "values.yml.j2" или
# "values.yaml.j2" в указанной директории (" .j2", потому что вы можете
# использовать обычные шаблоны Jinja2). Содержимое этого файла
# будет передано команде "helm install/template" как файл значений.
# По умолчанию директорией является "$HOME/traefik/helm". Если задание не находит такой файл, оно использует
# значения из "templates/traefik_values_default.yml.j2" по умолчанию.
traefik_chart_values_directory: "{{ '~/traefik/helm' | expanduser }}"
# По умолчанию CRD (определения пользовательских ресурсов) не устанавливаются. Установите на
# "true", если CRD должны быть установлены. Также смотрите:
# https://github.com/traefik/traefik-helm-chart/tree/master/traefik/crds
# Будут установлены следующие CRD:
# - ingressroutes.traefik.containo.us
# - ingressroutes.traefik.io
# - ingressroutetcps.traefik.containo.us
# - ingressroutetcps.traefik.io
# - ingressrouteudps.traefik.containo.us
# - ingressrouteudps.traefik.io
# - middlewares.traefik.containo.us
# - middlewares.traefik.io
# - middlewaretcps.traefik.containo.us
# - middlewaretcps.traefik.io
# - serverstransports.traefik.containo.us
# - serverstransports.traefik.io
# - tlsoptions.traefik.containo.us
# - tlsoptions.traefik.io
# - tlsstores.traefik.containo.us
# - tlsstores.traefik.io
# - traefikservices.traefik.containo.us
# - traefikservices.traefik.io
traefik_install_crds: false
# По умолчанию все задачи, которые должны взаимодействовать с кластером Kubernetes,
# выполняются на вашем локальном хосте (127.0.0.1). Но если тот хост
# не имеет прямого подключения к этому кластеру или задачи должны выполняться
# в другом месте, эту переменную можно изменить соответственно.
traefik_delegate_to: 127.0.0.1
# Показывает команду "helm", которая была выполнена, если задача использует Helm для
# установки, обновления или удаления такого ресурса.
traefik_helm_show_commands: false
# Без определения переменной "action" эта роль просто сгенерирует файл
# со всеми ресурсами, которые будут установлены или обновлены. Сгенерированный
# файл с ресурсами будет называться "template.yml" и будет
# помещен в директорию, указанную ниже.
traefik_template_output_directory: "{{ '~/traefik/template' | expanduser }}"
Использование
Первое, что нужно сделать, это проверить templates/traefik_values_default.yml.j2
. Этот файл содержит значения/настройки для Helm chart Traefik, которые отличаются от значений по умолчанию, расположенных здесь. Вот настройки по умолчанию:
# Все возможные значения Helm chart можно найти здесь:
# https://github.com/traefik/traefik-helm-chart/blob/master/traefik/values.yaml
image:
repository: traefik
tag: "2.11.2"
pullPolicy: IfNotPresent
# Эти аргументы передаются бинарному файлу Traefik. Для всех параметров см.:
# https://doc.traefik.io/traefik/reference/static-configuration/cli/
#
# Первый задает уровень логирования.
#
# Второй устанавливает значение аннотации "kubernetes.io/ingress.class"
# для наблюдения. Если объект "Ingress" стандартного Kubernetes
# передается серверу API Kubernetes (вместо собственного
# реализации Traefik, называемой "IngressRoute"), Traefik будет обрабатывать эти запросы
# и направлять их соответственно.
additionalArguments:
- "--log.level=INFO"
- "--providers.kubernetesingress.ingressclass=traefik"
# Глобальные аргументы, переданные бинарному файлу Traefik.
# https://doc.traefik.io/traefik/reference/static-configuration/cli/
#
# Первый отключает периодическую проверку наличия новой версии.
#
# Второй отключает анонимную статистику использования.
globalArguments:
- "--global.checknewversion=false"
- "--global.sendanonymoususage=false"
# Это создает развертывание Traefik. Поскольку здесь указано "DaemonSet",
# это создаст экземпляр Traefik на всех рабочих узлах Kubernetes. Если
# должен быть использован только подмножество узлов, укажите "affinity", "nodeSelector"
# или "toleration" соответственно. Смотрите ссылку на значения Helm chart выше.
deployment:
enabled: true
kind: DaemonSet
dnsPolicy: ClusterFirstWithHostNet
# Указывает Traefik слушать на различных портах.
ports:
# Имя этого порта нельзя изменять, так как оно используется для проверки готовности
# и живости, но вы можете настроить его конфигурацию по своему усмотрению.
# Чтобы получить доступ к панели управления, вы можете использовать "kubectl port-forward", например:
# kubectl -n traefik port-forward $(kubectl get pods --selector "app.kubernetes.io/name=traefik" --output=name -A | head -1) 9000:9000
# Открыв http://localhost:9000/dashboard/, вы должны увидеть панель управления.
traefik:
port: 9000
expose: false
protocol: TCP
# Небезопасный входящий HTTP-трафик. Если вы раскомментируете "redirectTo: websecure",
# весь трафик, который поступает на этот порт, будет перенаправлен на "websecure"
# входная точка, что означает входную точку, обрабатывающую безопасный HTTPS-трафик.
# Но будьте осторожны, это может быть проблематично для cert-manager.
# Также используется "hostPort". Поскольку выше был указан "DaemonSet", это
# означает, что поды Traefik будут отвечать на запросы на порту 80 и 443 на всех
# рабочих узлах Kubernetes. Если хосты имеют публичный IP и порты 80/443
# не защищены файрволом, Traefik доступен для запросов из
# Интернета (что обычно предполагается для Traefik ;-) ) Для других
# параметров смотрите ссылку выше. Эти настройки полезны для baremetal или
# решений на месте без дополнительных балансировщиков нагрузки.
web:
port: 30080
hostPort: 80
expose: true
protocol: TCP
# redirectTo: websecure
# Входная точка для HTTPS-трафика.
websecure:
port: 30443
hostPort: 443
expose: true
protocol: TCP
# Эти параметры безопасности являются лучшей практикой для минимизации поверхности атаки
# насколько это возможно.
# Поверхность атаки можно дополнительно ограничить с помощью "seccomp", который стабилен с
# Kubernetes v1.19 и позволяет ограничить системные вызовы до минимума. Смотрите:
# https://kubernetes.io/docs/tutorials/clusters/seccomp/"
securityContext:
capabilities:
drop:
- ALL
readOnlyRootFilesystem: true
runAsGroup: 65532
runAsNonRoot: true
runAsUser: 65532
# Все процессы контейнера также являются частью этого дополнительного идентификатора группы.
podSecurityContext:
fsGroup: 65532
# Устанавливает уровень логирования общего лога и включает доступ к логам.
logs:
general:
level: INFO
access:
enabled: true
# Поскольку порты web/websecure Traefik доступны через "hostPort", сервис не
# нужен.
service:
enabled: false
# Ограничения по ресурсам CPU и RAM. Эти настройки также должны быть установлены на
# разумные значения в случае утечки памяти, например.
resources:
requests:
cpu: "100m"
memory: "50Mi"
limits:
cpu: "300m"
memory: "150Mi"
# Обновляет поды в DaemonSet по одному, когда DaemonSet был обновлён.
updateStrategy:
type: RollingUpdate
rollingUpdate:
maxUnavailable: 1
Но ничего не предопределено ;-) Чтобы использовать ваши собственные значения, просто создайте файл с именем values.yml.j2
или values.yaml.j2
и поместите его в директорию, указанную в traefik_chart_values_directory
(которая по умолчанию равна $HOME/traefik/helm
). Затем эта роль будет использовать этот файл для создания значений Helm. Вы можете использовать templates/traefik_values_default.yml.j2
в качестве шаблона или просто начать с нуля. Как уже упоминалось, вы можете изменить все настройки для Helm chart, которые отличаются от значений по умолчанию, находящихся здесь.
После того как файл значений будет готов и проверены значения из defaults/main.yml
, роль может быть установлена. Большинство задач роли выполняются локально, поскольку многое из того, что требует ارتباطа с сервером API Kubernetes или выполнения команд Helm.
Действие по умолчанию — просто создать YAML-файл ресурсов Kubernetes после замены всех переменных Jinja2 и т.п. В разделе Example Playbook
ниже есть Example 2 (назначить тег роли)
. Роле githubixx.traefik-kubernetes
назначен тег role-traefik-kubernetes
. Предполагая, что значения для Helm chart должны быть сгенерированы (в этом случае ничего не будет установлено), а плейбук называется k8s.yml
, выполните следующую команду:
ansible-playbook --tags=role-traefik-kubernetes k8s.yml
Для того чтобы сгенерировать шаблон в другую директорию, используйте переменную traefik_template_output_directory
, например:
ansible-playbook --tags=role-traefik-kubernetes --extra-vars traefik_template_output_directory="/tmp/traefik" k8s.yml
Если вы хотите увидеть команды helm
и параметры, которые были выполнены в логах, вы также можете указать --extra-vars traefik_helm_show_commands=true
.
Одна из завершающих задач называется TASK [githubixx.traefik_kubernetes : Write templates to file]
. Это генерирует шаблон с ресурсами, которые будут созданы, в директорию, указанную в traefik_template_output_directory
. Файл будет называться template.yml
. Эта директория/файл будут помещены на вашей локальной машине, чтобы вы могли их проверить.
Если сгенерированный шаблон содержит всё, что вам нужно, роль может быть установлена, что окончательно развернёт Traefik:
ansible-playbook --tags=role-traefik-kubernetes --extra-vars action=install k8s.yml
Чтобы проверить, всё ли было развернуто, используйте обычные команды kubectl
, такие как kubectl -n <traefik_namespace> get pods -o wide
.
Поскольку Traefik выпускает обновления каждые несколько недель/месяцев, роль также может выполнять обновления. Этот метод также может быть использован для изменения существующих значений без обновления версии Traefik, например. Также смотрите релизы Traefik перед обновлением Traefik. Изменения в Helm chart можно найти в истории коммитов.
Если вы хотите обновить версию Traefik/Helm chart, вам в основном нужно изменить переменную traefik_chart_version
, например, с 10.21.1
на 10.24.2
. Возможно, вам также потребуется изменить значение image.tag
в templates/traefik_values_default.yml.j2
. Если только параметры должны быть изменены, обновите их соответствующим образом.
Итак, чтобы выполнить обновление Traefik или развернуть новые значения, выполните
ansible-playbook --tags=role-traefik-kubernetes --extra-vars action=upgrade k8s.yml
И, наконец, если вы хотите удалить Traefik, вы можете снова удалить все ресурсы:
ansible-playbook --tags=role-traefik-kubernetes --extra-vars action=delete k8s.yml
Пример плейбука
Пример 1 (без тега роли):
- hosts: traefik
roles:
- githubixx.traefik_kubernetes
Пример 2 (назначение тега роли):
-
hosts: traefik
roles:
-
role: githubixx.traefik-kubernetes
tags: role-traefik-kubernetes
Хост traefik
в примере плейбука, скорее всего, просто localhost
, указанный в файле хостов Ansible или любой другой хост, который вы хотите использовать как "исполнитель". Убедитесь, что этот хост имеет установленный helm
и имеет действующий kubeconfig
(что обычно так, если команда kubectl
работает с кластером Kubernetes).
Тестирование
Эта роль имеет небольшую тестовую настройку, которая создаётся с использованием Molecule, libvirt (vagrant-libvirt) и QEMU/KVM. Пожалуйста, посмотрите мой блог Тестирование ролей Ansible с помощью Molecule, libvirt (vagrant-libvirt) и QEMU/KVM, чтобы узнать, как настроить. Конфигурация теста здесь.
После этого можно выполнить molecule. Molecule создаст несколько ВМ с полным кластером Kubernetes, что позволит протестировать всю функциональность Traefik.
Следующая команда выполнит базовую настройку и создаст шаблон ресурсов (действие по умолчанию см. выше), которые будут созданы:
molecule converge
Установка Traefik
и необходимых ресурсов:
molecule converge -- --extra-vars action=install
Обновление Traefik
или изменение параметров:
molecule converge -- --extra-vars action=upgrade
Удаление Traefik
и его ресурсов:
molecule converge -- --extra-vars action=delete
Чтобы выполнить несколько тестов, используйте
molecule verify
Для очистки выполните
molecule destroy
Лицензия
GNU GENERAL PUBLIC LICENSE Версия 3
Информация об авторе
Ansible role to install Traefik ingress controller in a Kubernetes cluster
ansible-galaxy install githubixx/ansible-role-traefik-kubernetes