githubixx.traefik_kubernetes
traefik-kubernetes
このAnsibleロールは、Kubernetes用のTraefikエッジルーターをIngressコントローラーとしてインストールします。裏では公式のHelmチャートを使用しています。現在、Traefikのデプロイメントのインストール、更新/アップグレード、削除の手順がサポートされています。
提供されるデフォルトの設定は、TraefikがKubernetesサービスの公開エントリポイントであるベアメタル/オンプレミスのKubernetesクラスター向けに最適化されています。もちろん、Helmチャートと同様に構成をカスタマイズできますが、デフォルトの設定では以下の構成でTraefikがセットアップされます。
- Traefikインスタンスは
DaemonSetとしてデプロイされます。 - Traefikポッドは
hostPortを使用します。 - Traefikはホストの全インターフェースのポート
80でHTTPリクエストを受け付けます。 - Traefikはホストの全インターフェースのポート
443でHTTPSリクエストを受け付けます。 - Traefikダッシュボードは有効になっており、公開インターネットには公開されていません。
- TLS証明書はcert-managerによって提供されます（私のAnsibleロールcert-manager-kubernetesを使用してcert-managerをインストールできます）。
Helmチャートの設定に関する詳細情報は以下をご覧ください。
バージョン
リリースごとにタグを付けて、セマンティックバージョニングを維持するようにしています。このロールを使用したい場合は、最新のタグをチェックアウトすることをお勧めします。マスターブランチは基本的に開発中のもので、タグが安定したリリースを示しますが、一般的にマスターも良好な状態を保つようにしています。タグ5.0.0+23.0.1は、このロールのリリースが5.0.0であり、Helmチャートのバージョンが23.0.1であることを示します（使用されるTraefikのバージョンは値ファイルに指定されています[下記参照]）。ロール自体が変更されると、X.Y.Zの前の数字が増加します。Traefikチャートのバージョンが変更されると、X.Y.Zの後の数字も増加します。これにより、特定のTraefikリリース用に開発されている間に、バグ修正や新しいメジャーバージョンをタグ付けできます。
要件
ansible-playbookが実行されるホスト、またはプレイブックが委任されるホスト（例：traefik_delegate_to変数を使用）に、Helm 3のバイナリがインストールされている必要があります。以下のいずれかの方法でインストールできます：
- ディストリビューションのリポジトリに
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チャートバージョン
traefik_chart_version: "23.2.0"
# Helmリリース名
traefik_release_name: "traefik"
# Helmリポジトリ名
traefik_repo_name: "traefik"
# Helmチャート名
traefik_chart_name: "{{ traefik_repo_name }}/{{ traefik_release_name }}"
# HelmチャートのURL
traefik_chart_url: "https://helm.traefik.io/traefik"
# TraefikリソースをインストールするKubernetesネームスペース
traefik_namespace: "traefik"
# Helmチャートの値ファイルが含まれるディレクトリ。この変数を指定すると、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（カスタムリソース定義）はインストールされません。CRDをインストールする必要がある場合は、「true」に設定してください。詳細は以下を参照してください：
# 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を確認することです。このファイルには、デフォルトの設定（こちらにあります）とは異なるTraefik Helmチャートの値/設定が含まれています。以下は使用されるデフォルト設定です：
# すべての可能なHelmチャート値は、以下で確認できます：
# 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/
#
# 最初の引数はログレベルを設定します。
#
# 2番目の引数は「kubernetes.io/ingress.class」注釈の値を設定します。Kubernetes APIサーバに「標準」Kubernetes「Ingress」オブジェクトが送信されると、Traefikはこれらのリクエストを処理し、適切にルーティングします。
additionalArguments:
- "--log.level=INFO"
- "--providers.kubernetesingress.ingressclass=traefik"
# Traefikのバイナリに渡されるグローバル引数。
# https://doc.traefik.io/traefik/reference/static-configuration/cli/
#
# 最初の引数は新しいバージョンがリリースされたかどうかを定期的に確認する機能を無効にします。
#
# 2番目の引数は匿名の使用統計を無効にします。
globalArguments:
- "--global.checknewversion=false"
- "--global.sendanonymoususage=false"
# これはTraefikのデプロイメントを作成します。「DaemonSet」がここで指定されているため、KubernetesのすべてのワーカーノードにTraefikインスタンスが作成されます。もし特定のノード集合を使用する場合は、適切に「affinity」、「nodeSelector」または「toleration」を指定します。上記のHelmチャートの値を参照してください。
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"をコメント解除すると、このポートに到着するすべてのトラフィックが、セキュアなHTTPSトラフィックを処理する「websecure」エントリポイントにリダイレクトされます。
# ただし、これはcert-managerにとって問題がある可能性があります。 "hostPort"が使用されています。上で「DaemonSet」が指定されたため、基本的にTraefikポッドはKubernetesのすべてのワーカーノードでポート80と443に応答します。つまり、ホストに公開IPアドレスがあり、ポート80/443がファイアウォールで保護されていない場合、Traefikはインターネットからのリクエストに利用可能です（これはTraefikの場合、通常望むことです ;-)）。他のオプションについては、上記のリンクを参照してください。これらの設定は、ベアメタルまたはオンプレミスのソリューションで、追加のロードバランサーがない場合に便利です。
web:
port: 30080
hostPort: 80
expose: true
protocol: TCP
# redirectTo: websecure
# HTTPSトラフィックのためのエントリポイント。
websecure:
port: 30443
hostPort: 443
expose: true
protocol: TCP
# これらのセキュリティ設定は、攻撃対象面を可能な限り制限するためのベストプラクティスです。
# 攻撃対象面は、Kubernetes v1.19以降利用可能な「seccomp」を使用することでさらに制限できます。詳細は以下を参照してください：
# https://kubernetes.io/docs/tutorials/clusters/seccomp/"
securityContext:
capabilities:
drop:
- ALL
readOnlyRootFilesystem: true
runAsGroup: 65532
runAsNonRoot: true
runAsUser: 65532
# コンテナのすべてのプロセスもこの補助グループIDの一部です。
podSecurityContext:
fsGroup: 65532
# 一般的なログのログレベルを設定し、アクセスログを有効にします。
logs:
general:
level: INFO
access:
enabled: true
# Traefikのweb/websecureポートは「hostPort」によって公開されるため、サービスは必要ありません。
service:
enabled: false
# CPUおよびRAMのリソース制限。これらの設定は、メモリリークなどの場合に適切な値に設定する必要があります。
resources:
requests:
cpu: "100m"
memory: "50Mi"
limits:
cpu: "300m"
memory: "150Mi"
# DaemonSetがアップグレードされたときに、ポッドを1つずつ更新します。
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チャートのデフォルト値とは異なるすべての設定を変更できます。
値ファイルが配置され、defaults/main.ymlの値が確認された後、このロールをインストールできます。このロールのほとんどのタスクはローカルで実行されるため、Kubernetes APIサーバーと通信する必要があるタスクがいくつかあります。
デフォルトのアクションは、すべてのJinja2変数を置き換えた後、KubernetesリソースのYAMLファイルをレンダリングすることです。以下の「Example Playbook」セクションの「Example 2 (assign tag to role)」に示すように、ロールgithubixx.traefik-kubernetesにはタグrole-traefik-kubernetesが割り当てられています。Helmチャートの値がレンダリングされることを前提とし（この場合、何もインストールされません）、プレイブックが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チャートの変更は、コミット履歴で確認できます。
Traefik/Helmチャートをアップグレードするには、基本的にはtraefik_chart_version変数の値を変更します。例：10.21.1から10.24.2に。また、templates/traefik_values_default.yml.j2のimage.tag値も変更する必要があるかもしれません。パラメータのみを変更する場合は、値を適宜更新してください。
したがって、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は、Ansibleのhostsファイルで指定されたおそらくlocalhostであり、"ランナー"として使用したいホストです。単に、このホストにhelmがインストールされ、有効なkubeconfigがあることを確認してください（通常、kubectlコマンドがKubernetesクラスターで機能する場合は問題ありません）。
テスト
このロールには、小さなテストセットアップがあり、Molecule、libvirt（vagrant-libvirt）、およびQEMU/KVMを使用して作成されます。設定方法については、私のブログ投稿Testing Ansible roles with Molecule, libvirt (vagrant-libvirt) and QEMU/KVMをご覧ください。テスト構成はこちらで確認できます。
その後、Moleculeを実行できます。Moleculeは完全なKubernetesクラスターを持ついくつかのVMをセットアップし、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一般公衆ライセンス バージョン 3
著者情報
Ansible role to install Traefik ingress controller in a Kubernetes cluster
ansible-galaxy install githubixx.traefik_kubernetes