VictoriaMetrics/docs/operator/resources/vmauth.md

VMAuth

The VMAuth CRD provides mechanism for exposing application with authorization to outside world or to other applications inside kubernetes cluster.

For first case, user can configure ingress setting at VMAuth CRD. For second one, operator will create secret with username and password at VMUser CRD name. So it will be possible to access these credentials from any application by targeting corresponding kubernetes secret.

Specification

You can see the full actual specification of the VMAuth resource in the API docs -> VMAuth.

If you can't find necessary field in the specification of the custom resource, see Extra arguments section.

Also, you can check out the examples section.

Users

The CRD specifies which VMUsers should be covered by the deployed VMAuth instances based on label selection. The Operator then generates a configuration based on the included VMUsers and updates the Configmaps containing the configuration. It continuously does so for all changes that are made to VMUsers or to the VMAuth resource itself.

VMUser objects generate part of VMAuth configuration.

For filtering users VMAuth uses selectors userNamespaceSelector and userSelector. It allows configuring rules access control across namespaces and different environments. Specification of selectors you can see in this doc.

In addition to the above selectors, the filtering of objects in a cluster is affected by the field selectAllByDefault of VMAuth spec and environment variable WATCH_NAMESPACE for operator.

Following rules are applied:

• If userNamespaceSelector and userSelector both undefined, then by default select nothing. With option set - spec.selectAllByDefault: true, select all vmusers.
• If userNamespaceSelector defined, userSelector undefined, then all vmusers are matching at namespaces for given userNamespaceSelector.
• If userNamespaceSelector undefined, userSelector defined, then all vmusers at VMAgent's namespaces are matching for given userSelector.
• If userNamespaceSelector and userSelector both defined, then only vmusers at namespaces matched userNamespaceSelector for given userSelector are matching.

Here's a more visual and more detailed view:

userNamespaceSelector	userSelector	selectAllByDefault	WATCH_NAMESPACE	Selected rules
undefined	undefined	false	undefined	nothing
undefined	undefined	true	undefined	all vmusers in the cluster
defined	undefined	any	undefined	all vmusers are matching at namespaces for given userNamespaceSelector
undefined	defined	any	undefined	all vmusers only at VMAuth's namespace are matching for given userSelector
defined	defined	any	undefined	all vmusers only at namespaces matched userNamespaceSelector for given userSelector are matching
any	undefined	any	defined	all vmusers only at VMAuth's namespace
any	defined	any	defined	all vmusers only at VMAuth's namespace for given userSelector are matching

More details about WATCH_NAMESPACE variable you can read in this doc.

Here are some examples of VMAuth configuration with selectors:

# select all user objects in the cluster
apiVersion: operator.victoriametrics.com/v1beta1
kind: VMAuth
metadata:
  name: vmauth-select-all
spec:
  # ...
  selectAllByDefault: true

---

# select all user objects in specific namespace (my-namespace)
apiVersion: operator.victoriametrics.com/v1beta1
kind: VMAuth
metadata:
  name: vmauth-select-ns
spec:
  # ...
  userNamespaceSelector: 
    matchLabels:
      kubernetes.io/metadata.name: my-namespace

Unauthorized access

You can configure VMAuth to allow unauthorized access for specified routes with unauthorizedAccessConfig field.

For instance:

apiVersion: operator.victoriametrics.com/v1beta1
kind: VMAuth
metadata:
  name: vmauth-unauthorized-example
spec:
  unauthorizedAccessConfig:
    - paths: ["/metrics"]
      urls:
        - http://vmsingle-example.default.svc:8428

In this example every user can access /metrics route and get vmsingle metrics without authorization.

In addition, unauthorizedAccessConfig in Enterprise version supports IP Filters with ip_filters field.

High availability

The VMAuth resource is stateless, so it can be scaled horizontally by increasing the number of replicas:

apiVersion: operator.victoriametrics.com/v1beta1
kind: VMAuth
metadata:
  name: vmauth-example
spec:
    replicas: 3
    # ...

Version management

To set VMAuth version add spec.image.tag name from releases

apiVersion: operator.victoriametrics.com/v1beta1
kind: VMAuth
metadata:
  name: example-vmauth
spec:
  image:
    repository: victoriametrics/victoria-metrics
    tag: v1.93.4
    pullPolicy: Always
  # ...

Also, you can specify imagePullSecrets if you are pulling images from private repo:

apiVersion: operator.victoriametrics.com/v1beta1
kind: VMAuth
metadata:
  name: example-vmauth
spec:
  image:
    repository: victoriametrics/victoria-metrics
    tag: v1.93.4
    pullPolicy: Always
  imagePullSecrets:
    - name: my-repo-secret
# ...

Enterprise features

Custom resource VMAuth supports feature IP filters from VictoriaMetrics Enterprise.

For using Enterprise version of vmauth you need to change version of vmauth to version with -enterprise suffix using Version management.

All the enterprise apps require -eula command-line flag to be passed to them. This flag acknowledges that your usage fits one of the cases listed on this page. So you can use extraArgs for passing this flag to VMAuth:

IP Filters

After that you can use IP filters for VMUser and field ip_filters for VMAuth.

Here are complete example with described above:

apiVersion: operator.victoriametrics.com/v1beta1
kind: VMAuth
metadata:
  name: vmauth-ent-example
spec:
  # enabling enterprise features
  image:
    # enterprise version of vmauth
    tag: v1.93.5-enterprise
  extraArgs:
    # should be true and means that you have the legal right to run a vmauth enterprise
    # that can either be a signed contract or an email with confirmation to run the service in a trial period
    # https://victoriametrics.com/legal/esa/
    eula: true
  
  # using enterprise features: ip filters for vmauth
  # more details about ip filters you can read in https://docs.victoriametrics.com/vmauth.html#ip-filters
  ip_filters:
    allow_list:
      - 10.0.0.0/24
      - 1.2.3.4
    deny_list:
      - 5.6.7.8
  # allow read vmsingle metrics without authorization for users from internal network
  unauthorizedAccessConfig:
    - paths: ["/metrics"]
      urls: ["http://vmsingle-example.default.svc:8428"]
      ip_filters:
        allow_list:
          - 192.168.0.0/16
          - 10.0.0.0/8

  # ...other fields...

---

apiVersion: operator.victoriametrics.com/v1beta1
kind: VMUser
metadata:
  name: vmuser-ent-example
spec:
  username: simple-user
  password: simple-password

  # using enterprise features: ip filters for vmuser
  # more details about ip filters you can read in https://docs.victoriametrics.com/vmuser.html#enterprise-features
  ip_filters:
    allow_list:
      - 10.0.0.0/24
      - 1.2.3.4
    deny_list:
      - 5.6.7.8

Examples

apiVersion: operator.victoriametrics.com/v1beta1
kind: VMAuth
metadata:
  name: example
  namespace: default
spec:
  selectAllByDefault: true
  ingress:
    class_name: nginx # <-- change this to your ingress-controller
    host: vm-demo.k8s.orb.local # <-- change this to your domain