VMware vCenter

Early Access

This feature is currently in early access. Available starting v3.22.0-ea.1.

The vcenter provider discovers virtual machines (VMs) on VMware vCenter or directly on an ESXi host and builds routing configuration from each VM's extraConfig. It uses the same label model as the Docker and EC2 providers: you set traefik.* keys in a VM's extraConfig to define routers, services, middlewares, and load balancer settings, and the provider turns them into dynamic configuration.

Use it for workloads that run directly on VMware VMs, without a container orchestrator, and still need automatic service discovery and routing. When a VM powers on, powers off, or changes address, the provider updates the routing configuration.

Overview

The provider watches the vSphere inventory for VM changes instead of polling. It opens a container view on vCenter or ESXi and reacts to each create, update, and remove event as it happens. It filters VMs with constraint expressions and builds the routing configuration from each VM's extraConfig. The provider supports HTTP, TCP, and UDP services.

Key behaviors:

• Label-based configuration: You configure VMs through traefik.* keys in extraConfig, as with the Docker and EC2 providers.
• Event-driven discovery: The provider picks up changes as vCenter reports them, not on a polling interval.
• Powered-on VMs only, no templates: The provider ignores VM templates and VMs that are not powered on.
• No default routing rule: Unlike the ec2 provider, vcenter has no defaultRule. A VM without an explicit router rule key gets no router. See Routing Configuration with extraConfig.
• Service per VM: Each VM is its own service. The service name combines the VM's name and its vCenter identifier, so two VMs with the same name in different folders never merge into one service. See Provider Namespace.
• Backend addressing: Backends target the VM's guest IP address, as reported by VMware Tools, in the address family that ipMode selects.
• Flexible credentials: Authenticate with a vSphere username and password, or with the certificate of a vCenter SSO solution user. See Credentials.
• Cross-provider reference: Reference discovered resources from other providers by adding the @vcenter suffix to the name, for example a Kubernetes gateway that routes to a VM backend. See Provider Namespace.

Configuration Example

To use the vcenter provider, enable and configure it. The following example uses password authentication:

Install Configuration

hub:
  providers:
    vcenter:
      endpoint: "vcenter.example.com"
      username: "[email protected]"
      password: "changeme"
      exposedByDefault: false

Configuration Options

Field	Description	Default	Required
hub.providers.vcenter.endpoint	vCenter or ESXi endpoint: a host, a host:port, or a full URL. When no scheme is given, https:// is assumed.	""	Yes
hub.providers.vcenter.username	Username for password authentication. Requires password. Mutually exclusive with certificate/privateKey. See Credentials.	""	Yes*
hub.providers.vcenter.password	Password for password authentication. Requires username.	""	Yes*
hub.providers.vcenter.certificate	Certificate of the vCenter SSO solution user, for certificate authentication, as a file path or inline PEM content. Requires privateKey. Mutually exclusive with username/password. See Credentials.	""	Yes*
hub.providers.vcenter.privateKey	Private key of the vCenter SSO solution user, as a file path or inline PEM content. Requires certificate.	""	Yes*
hub.providers.vcenter.tls.insecureSkipVerify	Skip verification of the vCenter/ESXi server certificate.	false	No
hub.providers.vcenter.tls.ca	Path to the CA certificate file used to verify the vCenter/ESXi server certificate.	""	No
hub.providers.vcenter.tls.cert	Path to the client certificate file, for mutual TLS (mTLS) with vCenter/ESXi. Requires tls.key.	""	No
hub.providers.vcenter.tls.key	Path to the client private key file, for mutual TLS (mTLS) with vCenter/ESXi. Requires tls.cert.	""	No
hub.providers.vcenter.inventoryPath	Limits discovery to one branch of the vSphere inventory. See inventoryPath.	""	No
hub.providers.vcenter.exposedByDefault	Expose VMs by default. See exposedByDefault.	false	No
hub.providers.vcenter.constraints	Expression matched against a VM's extraConfig keys to determine whether to create routes for it. See constraints.	""	No
hub.providers.vcenter.ipMode	Default backend IP family: ipv4 or ipv6. Can be overridden per VM with the traefik.vcenter.ipmode key. See ipMode.	ipv4	No

* Exactly one of the two credential pairs is required. See Credentials.

endpoint

The vCenter or ESXi endpoint the provider connects to. endpoint must resolve to a host and must not carry credentials. When the path is empty or /, the provider uses the standard vSphere API path, /sdk.

Credentials

The provider authenticates against vCenter or ESXi in one of two ways. If you configure both or neither, the provider fails at startup.

• Password authentication: Set username and password together.
• Certificate authentication: Set certificate and privateKey together, using the certificate and key of a vCenter SSO solution user. The provider obtains a delegated security token for that user and logs in with it.

Password

Install Configuration

hub:
  providers:
    vcenter:
      endpoint: "vcenter.example.com"
      username: "[email protected]"
      password: "changeme"

Certificate

Install Configuration

hub:
  providers:
    vcenter:
      endpoint: "vcenter.example.com"
      certificate: "/etc/traefik/vcenter/sso-user.crt"
      privateKey: "/etc/traefik/vcenter/sso-user.key"

note

password and privateKey are sensitive values and are not logged.

extraConfig is not a secret store

Don't put credentials or other secrets in the value of a traefik.* key. The keys are part of the VM's configuration, and Traefik Hub can include the configuration it builds from them in its debug logs.

inventoryPath

Limits VM discovery to one branch of the vSphere inventory, for example a datacenter or a folder. When inventoryPath is empty, the provider watches every VM below the root folder. If the path doesn't resolve to an inventory object, the provider retries instead of stopping, so Traefik Hub can start before the path exists.

exposedByDefault

When exposedByDefault is true, the provider exposes every discovered VM unless the VM has the traefik.enable=false key. When exposedByDefault is false (the default), the provider ignores VMs that don't have the traefik.enable=true key.

Unlike the ec2 provider, where exposedByDefault defaults to true, vcenter defaults to false. A vSphere VM carries no port information the way an EC2 instance's security groups do, so a VM without traefik.* keys can never get a route. A default of true would only log an error for every unlabeled VM.

constraints

Set constraints to an expression that Traefik Hub matches against a VM's extraConfig keys. If the keys don't match the expression, the provider creates no route for that VM. If the expression is empty, the provider includes all detected VMs.

The expression uses the Label(`key`, `value`) and LabelRegex(`key`, `regex`) functions and the usual boolean operators, as the following examples show.

Constraints Expression Examples

# Includes only VMs having the key `a.key.name=foo`
constraints: "Label(`a.key.name`, `foo`)"

# Excludes VMs having the key `a.key.name=foo`
constraints: "!Label(`a.key.name`, `foo`)"

# With logical AND.
constraints: "Label(`env`, `production`) && Label(`tier`, `web`)"

# With logical OR.
constraints: "Label(`env`, `production`) || Label(`env`, `staging`)"

# With logical AND and OR, with precedence set by parentheses.
constraints: "Label(`env`, `production`) && (Label(`tier`, `web`) || Label(`tier`, `api`))"

# Includes only VMs whose `env` key value matches the `prod-.+` regular expression.
constraints: "LabelRegex(`env`, `prod-.+`)"

# Includes only VMs that carry the `env` key at all, whatever its value.
# Use `.+` rather than `.*`: `.*` also matches VMs that do not have the key.
constraints: "LabelRegex(`env`, `.+`)"

ipMode

ipMode selects the address family of a VM's guest IP that backends target:

• ipv4 (default): the VM's IPv4 address.
• ipv6: the VM's IPv6 address.

To override the mode for one VM, set the traefik.vcenter.ipmode key on that VM. The provider skips a VM that has no usable address for its mode.

note

VMware Tools, running inside the VM, reports the guest IP addresses. The provider skips a VM until VMware Tools is running and has reported an address. The provider never uses loopback or link-local addresses.

Routing Configuration with extraConfig

The provider reads traefik.* keys from each VM's extraConfig and decodes them into routers, services, and middlewares, as the other label-based providers do. Provider-specific options use the traefik.vcenter. prefix. Examples:

Key	Description
traefik.enable	Whether to expose the VM. Interacts with exposedByDefault.
traefik.vcenter.ipmode	Overrides the provider-level ipMode for this VM (ipv4 or ipv6).
traefik.http.routers.<name>.rule	Defines the routing rule for an HTTP router.
traefik.http.services.<name>.loadbalancer.server.port	Sets the backend port for an HTTP service.
traefik.tcp.routers.<name>.rule	Defines the routing rule for a TCP router.
traefik.udp.routers.<name>.entrypoints	Assigns entry points for a UDP router.

The full set of routing keys follows the naming of the standard Traefik label-based providers. The Docker provider labels page documents the complete label and tag syntax. For example, use traefik.http.middlewares.<name>.<middleware-type>.<option> to configure middlewares, or traefik.http.services.<name>.loadbalancer.server.scheme to set the backend scheme.

Example VM extraConfig

traefik.enable=true
traefik.http.routers.my-app.rule=Host(`my-app.example.com`)
traefik.http.services.my-app.loadbalancer.server.port=8080

These keys create an HTTP router that matches Host(`my-app.example.com`) and a service whose backend is the VM's guest IP on port 8080.

No default routing rule

The ec2 provider falls back to a defaultRule when a tag doesn't define a router rule. The vcenter provider has no fallback. A VM without a traefik.http.routers.<name>.rule key (or the TCP or UDP equivalent) gets no router, because a VM isn't reachable by its name the way a container is. As a result, the provider can discover a VM as a service without creating a route for it, for example to reference the VM from another provider with the @vcenter suffix. You need no extra key to suppress the router.

Provider Namespace

The vcenter provider creates the resources it discovers in the vcenter provider namespace. To reference such a resource from another provider, add the @vcenter suffix to its name:

<resource-name>@vcenter

Each VM becomes its own service. The service name combines the VM's name and its vCenter identifier, so two VMs with the same name in different folders never merge into one service. The ec2 provider behaves differently: it merges EC2 instances that share the same Name tag into one service.

For more details on provider namespaces, see the providers overview.

Additional Notes

• The provider discovers only VMs that are powered on, and never discovers VM templates.
• Backends use the address that ipMode selects. The provider skips a VM that has no address for that mode.
• The provider keeps the vCenter session alive between updates, so it doesn't need to log in again after a long idle period with no inventory changes.
• When the connection drops, the provider retries with exponential backoff and keeps the last valid configuration until the next successful update.