traefik_proxmox_provider

README

Traefik Proxmox Provider

A Traefik provider that automatically configures routing based on Proxmox VE virtual machines and containers.

Features

• Automatically discovers Proxmox VE virtual machines and containers
• Configures routing based on VM/container metadata
• Supports both HTTP and HTTPS endpoints
• Configurable polling interval
• SSL validation options
• Logging configuration
• Full support for Traefik's routing, middleware, and TLS options

Installation

1. Add the plugin to your Traefik configuration:

experimental:
  plugins:
    traefik-proxmox-provider:
      moduleName: github.com/NX211/traefik-proxmox-provider
      version: v0.7.0

1. Configure the provider in your dynamic configuration:

# Dynamic configuration
providers:
  plugin:
    traefik-proxmox-provider:
      pollInterval: "30s"
      apiEndpoint: "https://proxmox.example.com"
      apiTokenId: "root@pam!traefik_prod"
      apiToken: "your-api-token"
      apiLogging: "info"
      apiValidateSSL: "true"

Configuration

Provider Options

Option	Type	Default	Description
pollInterval	string	"30s"	How often to poll the Proxmox API for changes
apiEndpoint	string	-	The URL of your Proxmox VE API
apiTokenId	string	-	The API token ID (e.g., "root@pam!traefik_prod")
apiToken	string	-	The API token secret
apiLogging	string	"info"	Log level for API operations ("debug" or "info")
apiValidateSSL	string	"true"	Whether to validate SSL certificates

Proxmox API Token Setup

The Traefik Proxmox Provider needs an API token with specific permissions to read VM and container information. Here's how to set up the proper token and permissions:

# Create a role for Traefik provider with minimum required permissions

## For Proxmox VE 8.x or earlier:
pveum role add traefik-provider -privs "VM.Audit,VM.Monitor,Sys.Audit,Datastore.Audit"

## For Proxmox VE 9.0 or later (VM.Monitor was removed and replaced with granular privileges):
pveum role add traefik-provider -privs "VM.Audit,VM.GuestAgent.Audit,Sys.Audit,Datastore.Audit"

# Create an API token for your user (replace with your actual username)
pveum user token add root@pam traefik_prod

# Assign the role to the token for all paths
pveum acl modify / -token 'root@pam!traefik_prod' -role traefik-provider

Note: If you are upgrading from Proxmox VE 8.x to 9.x, you must update your API token role. The VM.Monitor privilege was removed in PVE 9.0 and replaced with VM.GuestAgent.Audit (required for reading VM network interfaces via the QEMU guest agent). Without this, the provider will receive 403 errors when discovering VM IP addresses.

Make sure to save the API token value when it's displayed, as it won't be shown again.

Usage

1. Create an API token in Proxmox VE as described above

2. Configure the provider in your Traefik configuration:

   • Set the apiEndpoint to your Proxmox VE server URL
   • Set the apiTokenId and apiToken from step 1
   • Adjust other options as needed

3. Very Important: Add Traefik labels to your VMs/containers:

   • Edit your VM/container in Proxmox VE
   • Go to the "Summary" page and edit the "Notes" box by clicking the pencil icon
   • Add one Traefik label per line with the format traefik.key=value
   • At minimum add traefik.enable=true to enable Traefik for this VM/container

4. Restart Traefik to load the new configuration

VM/Container Labeling

The provider looks for Traefik labels in the VM/container notes field. Each line in the Notes field starting with traefik. will be treated as a Traefik label.

Required Labels

• traefik.enable=true - Without this label, the VM/container will be ignored

Common Labels

• traefik.http.routers.<name>.rule=Host(myapp.example.com) - The router rule for this service
• traefik.http.services.<name>.loadbalancer.server.port=8080 - The port to route traffic to (defaults to 80)

Advanced Label Examples

Named Routers and Services

traefik.enable=true
traefik.http.routers.myapp.rule=Host(`myapp.example.com`)
traefik.http.services.appservice.loadbalancer.server.port=8080
traefik.http.routers.myapp.service=appservice

EntryPoints

traefik.http.routers.myapp.entrypoints=websecure

Middlewares

traefik.http.routers.myapp.middlewares=compression,auth@file

TLS Configuration

traefik.http.routers.myapp.tls=true
traefik.http.routers.myapp.tls.certresolver=myresolver
traefik.http.routers.myapp.tls.domains=example.com
traefik.http.routers.myapp.tls.options=tlsoptions@file

Health Checks

traefik.http.services.myservice.loadbalancer.healthcheck.path=/health
traefik.http.services.myservice.loadbalancer.healthcheck.interval=10s
traefik.http.services.myservice.loadbalancer.healthcheck.timeout=5s

Sticky Sessions

traefik.http.services.myservice.loadbalancer.sticky.cookie.name=session
traefik.http.services.myservice.loadbalancer.sticky.cookie.secure=true
traefik.http.services.myservice.loadbalancer.sticky.cookie.httponly=true

HTTPS Backend Services

traefik.http.services.myservice.loadbalancer.server.scheme=https

Full Example of VM/Container Notes

My application server
Some notes about this server

traefik.enable=true
traefik.http.routers.myapp.rule=Host(`myapp.example.com`)
traefik.http.routers.myapp.entrypoints=websecure
traefik.http.routers.myapp.middlewares=auth@file,compression
traefik.http.routers.myapp.tls=true
traefik.http.routers.myapp.tls.certresolver=myresolver
traefik.http.services.myapp.loadbalancer.server.port=8080
traefik.http.services.myapp.loadbalancer.healthcheck.path=/health

How It Works

1. The provider connects to your Proxmox VE cluster via API
2. It discovers all running VMs and containers on all nodes
3. For each VM/container, it reads the notes field looking for Traefik labels
4. If traefik.enable=true is found, it creates a Traefik router and service
5. The provider attempts to get IP addresses for the VM/container
6. If IPs are found, they're used as server URLs; otherwise, the VM/container hostname is used
7. This process repeats according to the configured poll interval

Examples

Basic Configuration

providers:
  plugin:
    traefik-proxmox-provider:
      pollInterval: "30s"
      apiEndpoint: "https://proxmox.example.com"
      apiTokenId: "root@pam!traefik_prod"
      apiToken: "your-api-token"
      apiLogging: "debug"  # Use debug for troubleshooting
      apiValidateSSL: "true"

VM/Container Label Examples

Simple web server:

traefik.enable=true
traefik.http.routers.app.rule=Host(`myapp.example.com`)

Secure website with HTTPS:

traefik.enable=true
traefik.http.routers.secure.rule=Host(`secure.example.com`)
traefik.http.routers.secure.entrypoints=websecure
traefik.http.routers.secure.tls=true
traefik.http.routers.secure.tls.certresolver=dnschallenge

API with authentication and rate limiting:

traefik.enable=true
traefik.http.routers.api.rule=Host(`api.example.com`)
traefik.http.routers.api.middlewares=auth@file,ratelimit@file
traefik.http.services.api.loadbalancer.server.port=3000

Multiple hosts with path-based routing:

traefik.enable=true
traefik.http.routers.multi.rule=Host(`example.com`,`www.example.com`) && PathPrefix(`/api`)
traefik.http.routers.multi.priority=100

Troubleshooting

If your services aren't being discovered:

1. Enable debug logging by setting apiLogging: "debug"
2. Check that VMs/containers have traefik.enable=true in their notes field
3. Verify that VMs/containers are in the "running" state
4. Check that the provider can successfully connect to your Proxmox API
5. Verify the API token has sufficient permissions
6. Check the Traefik logs for any errors related to entrypoints or middleware references

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

Overview

Package traefik_proxmox_provider is a plugin to use a proxmox cluster as a provider for Traefik.

Index

• type Config
  • func CreateConfig() *Config
• type Provider
  • func New(ctx context.Context, config *Config, name string) (*Provider, error)
  • func (p *Provider) Init() error
  • func (p *Provider) Provide(cfgChan chan<- json.Marshaler) error
  • func (p *Provider) Stop() error

Types

type Config

type Config struct {
	PollInterval   string `json:"pollInterval" yaml:"pollInterval" toml:"pollInterval"`
	ApiEndpoint    string `json:"apiEndpoint" yaml:"apiEndpoint" toml:"apiEndpoint"`
	ApiTokenId     string `json:"apiTokenId" yaml:"apiTokenId" toml:"apiTokenId"`
	ApiToken       string `json:"apiToken" yaml:"apiToken" toml:"apiToken"`
	ApiLogging     string `json:"apiLogging" yaml:"apiLogging" toml:"apiLogging"`
	ApiValidateSSL string `json:"apiValidateSSL" yaml:"apiValidateSSL" toml:"apiValidateSSL"`
}

Config the plugin configuration.

func CreateConfig

func CreateConfig() *Config

CreateConfig creates the default plugin configuration.

type Provider

type Provider struct {
	// contains filtered or unexported fields
}

Provider a plugin.

func New

func New(ctx context.Context, config *Config, name string) (*Provider, error)

New creates a new Provider plugin.

func (*Provider) Init

func (p *Provider) Init() error

Init initializes the provider.

func (*Provider) Provide

func (p *Provider) Provide(cfgChan chan<- json.Marshaler) error

Provide creates and sends dynamic configuration.

func (*Provider) Stop

func (p *Provider) Stop() error

Stop the provider.