VictoriaMetrics/docs/operator/resources/vmsingle.md

sort	weight	title	menu	aliases
12	12	VMSingle	docs parent weight operator-custom-resources 12	/operator/resources/vmsingle.html

VMSingle

VMSingle represents database for storing metrics. The VMSingle CRD declaratively defines a single-node VM installation to run in a Kubernetes cluster.

For each VMSingle resource, the Operator deploys a properly configured Deployment in the same namespace. The VMSingle Pods are configured to mount an empty dir or PersistentVolumeClaimSpec for storing data. Deployment update strategy set to recreate. No more than one replica allowed.

For each VMSingle resource, the Operator adds Service and VMServiceScrape in the same namespace prefixed with name from VMSingle.metadata.name.

Specification

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

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.

High availability

VMSingle doesn't support high availability by default, for such purpose use VMCluster instead or duplicate the setup.

Version management

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

apiVersion: operator.victoriametrics.com/v1beta1
kind: VMSingle
metadata:
  name: example-vmsingle
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: VMSingle
metadata:
  name: example-vmsingle
spec:
  image:
    repository: victoriametrics/victoria-metrics
    tag: v1.93.4
    pullPolicy: Always
  imagePullSecrets:
    - name: my-repo-secret
# ...

Resource management

You can specify resources for each VMSingle resource in the spec section of the VMSingle CRD.

apiVersion: operator.victoriametrics.com/v1beta1
kind: VMSingle
metadata:
  name: vmsingle-resources-example
spec:
    # ...
    resources:
        requests:
          memory: "64Mi"
          cpu: "250m"
        limits:
          memory: "128Mi"
          cpu: "500m"
    # ...

If these parameters are not specified, then, by default all VMSingle pods have resource requests and limits from the default values of the following operator parameters:

• VM_VMSINGLEDEFAULT_RESOURCE_LIMIT_MEM - default memory limit for VMSingle pods,
• VM_VMSINGLEDEFAULT_RESOURCE_LIMIT_CPU - default memory limit for VMSingle pods,
• VM_VMSINGLEDEFAULT_RESOURCE_REQUEST_MEM - default memory limit for VMSingle pods,
• VM_VMSINGLEDEFAULT_RESOURCE_REQUEST_CPU - default memory limit for VMSingle pods.

These default parameters will be used if:

• VM_VMSINGLEDEFAULT_USEDEFAULTRESOURCES is set to true (default value),
• VMSingle CR doesn't have resources field in spec section.

Field resources in VMSingle spec have higher priority than operator parameters.

If you set VM_VMSINGLEDEFAULT_USEDEFAULTRESOURCES to false and don't specify resources in VMSingle CRD, then VMSingle pods will be created without resource requests and limits.

Also, you can specify requests without limits - in this case default values for limits will not be used.

Enterprise features

VMSingle supports features from VictoriaMetrics Enterprise:

• Downsampling
• Multiple retentions / Retention filters
• Backup automation

For using Enterprise version of vmsingle you need to change version of VMSingle 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 VMSingle.

Downsampling

After that you can pass Downsampling flag to VMSingle with extraArgs too.

Here are complete example for Downsampling:

apiVersion: operator.victoriametrics.com/v1beta1
kind: VMSingle
metadata:
  name: vmsingle-ent-example
spec:
  # enabling enterprise features
  image:
    # enterprise version of vmsingle
    tag: v1.93.5-enterprise
  extraArgs:
    # should be true and means that you have the legal right to run a vmsingle 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: Downsampling
    # more details about downsampling you can read on https://docs.victoriametrics.com/#downsampling
    downsampling.period: 30d:5m,180d:1h,1y:6h,2y:1d

  # ...other fields...

Retention filters

The same method is used to enable retention filters - here are complete example for Retention filters.

apiVersion: operator.victoriametrics.com/v1beta1
kind: VMSingle
metadata:
  name: vmsingle-ent-example
spec:
  # enabling enterprise features
  image:
    # enterprise version of vmsingle
    tag: v1.93.5-enterprise
  extraArgs:
    # should be true and means that you have the legal right to run a vmsingle 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: Retention filters
    # more details about retention filters you can read on https://docs.victoriametrics.com/#retention-filters
    retentionFilter: '{team="juniors"}:3d,{env=~"dev|staging"}:30d'

  # ...other fields...

Backup automation

You can check vmbackupmanager documentation for backup automation. It contains a description of the service and its features. This section covers vmbackumanager integration in vmoperator.

VMSingle has built-in backup configuration, it uses vmbackupmanager - proprietary tool for backups. It supports incremental backups (hourly, daily, weekly, monthly) with popular object storages (aws s3, google cloud storage).

Here is a complete example for backup configuration:

apiVersion: operator.victoriametrics.com/v1beta1
kind: VMSingle
metadata:
  name: example-vmsingle
spec:

  vmBackup:
    # should be true and means that you have the legal right to run a vmsingle 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/
    acceptEULA: true

    # using enterprise features: Backup automation
    # more details about backup automation you can read on https://docs.victoriametrics.com/vmbackupmanager.html      
    destination: "s3://your_bucket/folder"
    credentialsSecret:
      name: remote-storage-keys
      key: credentials

  # ...other fields...

---

apiVersion: v1
kind: Secret
metadata:
  name: remote-storage-keys
type: Opaque
stringData:
  credentials: |-
    [default]
    aws_access_key_id = your_access_key_id
    aws_secret_access_key = your_secret_access_key    

You can read more about backup configuration options and mechanics here

Possible configuration options for backup crd can be found at link

Restoring backups

There are several ways to restore with vmrestore or vmbackupmanager.

Manually mounting disk

You have to stop VMSingle by scaling it replicas to zero and manually restore data to the database directory.

Steps:

1. Edit VMSingle CRD, set replicaCount: 0
2. Wait until database stops
3. SSH to some server, where you can mount VMSingle disk and mount it manually
4. Restore files with vmrestore
5. Umount disk
6. Edit VMSingle CRD, set replicaCount: 1
7. Wait database start

Using VMRestore init container

1. Add init container with vmrestore command to VMSingle CRD, example:

   apiVersion: operator.victoriametrics.com/v1beta1
   kind: VMSingle
   metadata:
     name: example-vmsingle
   spec:
   
     vmBackup:
       # should be true and means that you have the legal right to run a vmsingle 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/
       acceptEULA: true
   
       # using enterprise features: Backup automation
       # more details about backup automation you can read on https://docs.victoriametrics.com/vmbackupmanager.html      
       destination: "s3://your_bucket/folder"
       credentialsSecret:
         name: remote-storage-keys
         key: credentials
   
     extraArgs:
       runOnStart: "true"
   
     initContainers:
       - name: vmrestore
         image: victoriametrics/vmrestore:latest
         volumeMounts:
           - mountPath: /victoria-metrics-data
             name: data
           - mountPath: /etc/vm/creds
             name: secret-remote-storage-keys
             readOnly: true
         args:
           - -storageDataPath=/victoria-metrics-data
           - -src=s3://your_bucket/folder/latest
           - -credsFilePath=/etc/vm/creds/credentials
   
     # ...other fields...
   

2. Apply it, and db will be restored from S3
3. Remove initContainers and apply CRD.

Note that using VMRestore will require adjusting src for each pod because restore will be handled per-pod.

Using VMBackupmanager init container

Using VMBackupmanager restore in Kubernetes environment is described here.

Advantages of using VMBackupmanager include:

• Automatic adjustment of src for each pod when backup is requested
• Graceful handling of case when no restore is required - VMBackupmanager will exit with successful status code and won't prevent pod from starting

Examples

apiVersion: operator.victoriametrics.com/v1beta1
kind: VMSingle
metadata:
  name: vmsingle-example
spec:
  retentionPeriod: "12"
  removePvcAfterDelete: true
  storage:
    accessModes:
      - ReadWriteOnce
    resources:
      requests:
        storage: 50Gi
  extraArgs:
    dedup.minScrapeInterval: 60s
  resources:
    requests:
      memory: 500Mi
      cpu: 500m
    limits:
      memory: 10Gi
      cpu: 5