volsync

package
v0.2.0-beta.21 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 28, 2026 License: Apache-2.0 Imports: 2 Imported by: 0

README

VolSync Builders - ReplicationSource and ReplicationDestination

Go Reference

The volsync package provides the generated constructors and the admissible sugar for VolSync (volsync.backube/v1alpha1) resources. It is the canonical entry point for building ReplicationSource and ReplicationDestination objects in kure.

Overview

VolSync replicates persistent volume data between Kubernetes clusters. Each replication direction (source and destination) selects exactly one mover — the data-transfer backend — from a sum of choices: Restic, Rsync (legacy SSH), RsyncTLS, Rclone, Syncthing (source-only), or an External passthrough.

The upstream spec encodes that one-of as a pointer per arm (Spec.Restic, Spec.Rsync, Spec.RsyncTLS, Spec.Rclone, Spec.Syncthing, Spec.External); set the one you mean and leave the others nil. VolSync rejects a spec with two arms at apply time. See docs/ARCHITECTURE.md § One-of Constraints for how kure treats these.

Each block on this page is the body of an Example function in example_test.go, which go test runs: it imports this package as volsync, the upstream API as volsyncv1alpha1 "github.com/backube/volsync/api/v1alpha1", corev1 "k8s.io/api/core/v1", k8s.io/apimachinery/pkg/api/resource, k8s.io/utils/ptr, and fmt for the line that prints what the example built.

Constructors

Every kind this package registers has a generated Create<Kind> wrapper in zz_generated_create.go, produced from the scheme by pkg/kubernetes/internal/gen (make gen-builders, checked by make check-builders in CI). A wrapper delegates to kubernetes.Create[T] and emits TypeMeta and identity only: no default, no label, no spec value. Both kinds are namespaced and take (name, namespace).

obj := volsync.CreateReplicationSource("db-backup", "data")
fmt.Println(obj.Kind, obj.Namespace+"/"+obj.Name)

There is no second construction path. The config-struct layer this package used to carry (volsync.ReplicationSource(&volsync.ReplicationSourceConfig{...}), ReplicationDestination, the TriggerConfig and the sealed SourceMover / DestinationMover sums with their nine defined-over-upstream mover types) was retired by release 2 of the builder contract: the movers were the upstream specs under another name, and the sealed interfaces walled off nothing the upstream struct did not already carry. The release 2 migration notes map every removed field to the upstream field that replaces it. No hand-written Create* helper for a spec fragment remains either — a sub-type that is not a client.Object takes a struct literal, which is shorter and shows every field being set.

The kinds this package registers, their scope, and what stated that scope are rows in the generated Supported kinds and field maturity tables. The sections below are worked examples, not the coverage list.

See the Kubernetes Builders page for the full builder contract: construction, sugar admission classes, purity and the migration ledgers.

Supported Resources

Resource Movers
ReplicationSource Restic · Rsync · RsyncTLS · Rclone · Syncthing · External
ReplicationDestination Restic · Rsync · RsyncTLS · Rclone · External

ReplicationSource

rs := volsync.CreateReplicationSource("db-backup", "data")
rs.Spec = volsyncv1alpha1.ReplicationSourceSpec{
    SourcePVC: "postgres-data",
    Trigger:   &volsyncv1alpha1.ReplicationSourceTriggerSpec{Schedule: ptr.To("@hourly")},
    Restic: &volsyncv1alpha1.ReplicationSourceResticSpec{
        Repository: "restic-creds",
        ReplicationSourceVolumeOptions: volsyncv1alpha1.ReplicationSourceVolumeOptions{
            CopyMethod: volsync.CopyMethodSnapshot,
        },
        Retain: &volsyncv1alpha1.ResticRetainPolicy{
            Daily:   ptr.To[int32](7),
            Weekly:  ptr.To[int32](4),
            Monthly: ptr.To[int32](12),
        },
    },
}
fmt.Println(rs.Spec.SourcePVC, *rs.Spec.Trigger.Schedule, rs.Spec.Restic.CopyMethod)

ReplicationDestination

capacity := resource.MustParse("10Gi")

rd := volsync.CreateReplicationDestination("db-restore", "dr")
rd.Spec = volsyncv1alpha1.ReplicationDestinationSpec{
    Trigger: &volsyncv1alpha1.ReplicationDestinationTriggerSpec{Manual: "restore-1"},
    Restic: &volsyncv1alpha1.ReplicationDestinationResticSpec{
        Repository: "restic-creds",
        ReplicationDestinationVolumeOptions: volsyncv1alpha1.ReplicationDestinationVolumeOptions{
            CopyMethod:  volsync.CopyMethodSnapshot,
            Capacity:    &capacity,
            AccessModes: []corev1.PersistentVolumeAccessMode{corev1.ReadWriteOnce},
        },
    },
}
fmt.Println(rd.Spec.Trigger.Manual, rd.Spec.Restic.Capacity.String())

Movers

Mover Spec field Purpose
Restic Spec.Restic Encrypted, deduplicated snapshots to a restic repository (S3, B2, etc.).
Rsync Spec.Rsync Legacy SSH-based rsync. Prefer RsyncTLS for new deployments.
RsyncTLS Spec.RsyncTLS rsync over a TLS pre-shared key.
Rclone Spec.Rclone Sync to/from any rclone-supported backend (S3, GCS, Azure, etc.).
Syncthing Spec.Syncthing Continuous bidirectional sync over the Syncthing protocol (source resource only).
External Spec.External Passthrough for custom replication providers — opaque provider + parameters.

Modifying a resource

The upstream struct is the only mutation surface this package offers. To change a built resource, assign the field:

rs := volsync.CreateReplicationSource("db-backup", "data")

rs.Spec.Paused = false
rs.Spec.Trigger = &volsyncv1alpha1.ReplicationSourceTriggerSpec{Manual: "go"}
fmt.Println(rs.Spec.Trigger.Manual)

Switching a mover on an existing resource means clearing the other arms yourself — five on a source, four on a destination, which has no Syncthing mover — exactly the multi-field write the builder contract forbids a Set<Field> helper from hiding.

The one appender remains, because a peer list is a slice the contract admits sugar for; it takes the upstream Syncthing spec, which is the value assigned to Spec.Syncthing:

rs := volsync.CreateReplicationSource("db-backup", "data")

rs.Spec.Syncthing = &volsyncv1alpha1.ReplicationSourceSyncthingSpec{}
volsync.AddSyncthingPeer(rs.Spec.Syncthing, "tcp://peer:22000", "PEER-ID", false)
fmt.Println(rs.Spec.Syncthing.Peers[0].ID, rs.Spec.Syncthing.Peers[0].Address)

CopyMethod and its four constants (CopyMethodDirect, CopyMethodNone, CopyMethodClone, CopyMethodSnapshot) re-export the upstream copy-method type for convenience; volsyncv1alpha1.CopyMethodSnapshot is the same value.

Documentation

Overview

Package volsync exposes the generated constructors and the admissible sugar for VolSync (volsync.backube/v1alpha1) resources: ReplicationSource and ReplicationDestination. Each constructor returns a controller-runtime object carrying identity only; the upstream volsyncv1alpha1 struct is the construction API.

A replication's mover is the upstream one-of: a pointer per arm on the spec (Restic, Rsync, RsyncTLS, Rclone, Syncthing on a source, External). Set the one you mean and leave the others nil.

rs := volsync.CreateReplicationSource("db-backup", "data")
rs.Spec = volsyncv1alpha1.ReplicationSourceSpec{
    SourcePVC: "postgres-data",
    Trigger:   &volsyncv1alpha1.ReplicationSourceTriggerSpec{Schedule: ptr.To("@hourly")},
    Restic: &volsyncv1alpha1.ReplicationSourceResticSpec{
        Repository: "restic-creds",
        ReplicationSourceVolumeOptions: volsyncv1alpha1.ReplicationSourceVolumeOptions{
            CopyMethod: volsync.CopyMethodSnapshot,
        },
    },
}

AddSyncthingPeer appends to a Syncthing mover's peer list; CopyMethod and its constants re-export the upstream copy-method type.

The config-struct layer this package used to carry — ReplicationSource and ReplicationDestination taking a *Config whose Mover was a sealed SourceMover / DestinationMover sum — was retired by release 2 of the builder contract; see docs/builder-contract-release-2.md for the field-by-field mapping.

Index

Examples

Constants

View Source
const (
	CopyMethodDirect   = volsyncv1alpha1.CopyMethodDirect
	CopyMethodNone     = volsyncv1alpha1.CopyMethodNone
	CopyMethodClone    = volsyncv1alpha1.CopyMethodClone
	CopyMethodSnapshot = volsyncv1alpha1.CopyMethodSnapshot
)

Variables

This section is empty.

Functions

func AddSyncthingPeer

func AddSyncthingPeer(spec *volsyncv1alpha1.ReplicationSourceSyncthingSpec, address, id string, introducer bool)

AddSyncthingPeer appends a peer to a ReplicationSource's Syncthing mover spec, the value assigned to rs.Spec.Syncthing.

Example
package main

import (
	"fmt"

	volsyncv1alpha1 "github.com/backube/volsync/api/v1alpha1"

	"github.com/go-kure/kure/pkg/kubernetes/volsync"
)

func main() {
	rs := volsync.CreateReplicationSource("db-backup", "data")

	rs.Spec.Syncthing = &volsyncv1alpha1.ReplicationSourceSyncthingSpec{}
	volsync.AddSyncthingPeer(rs.Spec.Syncthing, "tcp://peer:22000", "PEER-ID", false)
	fmt.Println(rs.Spec.Syncthing.Peers[0].ID, rs.Spec.Syncthing.Peers[0].Address)
}
Output:
PEER-ID tcp://peer:22000

func CreateReplicationDestination

func CreateReplicationDestination(name, namespace string) *volsyncv1alpha1.ReplicationDestination

CreateReplicationDestination returns a volsync.backube/v1alpha1 ReplicationDestination carrying TypeMeta and identity only.

Example
package main

import (
	"fmt"

	volsyncv1alpha1 "github.com/backube/volsync/api/v1alpha1"
	corev1 "k8s.io/api/core/v1"
	"k8s.io/apimachinery/pkg/api/resource"

	"github.com/go-kure/kure/pkg/kubernetes/volsync"
)

func main() {
	capacity := resource.MustParse("10Gi")

	rd := volsync.CreateReplicationDestination("db-restore", "dr")
	rd.Spec = volsyncv1alpha1.ReplicationDestinationSpec{
		Trigger: &volsyncv1alpha1.ReplicationDestinationTriggerSpec{Manual: "restore-1"},
		Restic: &volsyncv1alpha1.ReplicationDestinationResticSpec{
			Repository: "restic-creds",
			ReplicationDestinationVolumeOptions: volsyncv1alpha1.ReplicationDestinationVolumeOptions{
				CopyMethod:  volsync.CopyMethodSnapshot,
				Capacity:    &capacity,
				AccessModes: []corev1.PersistentVolumeAccessMode{corev1.ReadWriteOnce},
			},
		},
	}
	fmt.Println(rd.Spec.Trigger.Manual, rd.Spec.Restic.Capacity.String())
}
Output:
restore-1 10Gi

func CreateReplicationSource

func CreateReplicationSource(name, namespace string) *volsyncv1alpha1.ReplicationSource

CreateReplicationSource returns a volsync.backube/v1alpha1 ReplicationSource carrying TypeMeta and identity only.

Example
package main

import (
	"fmt"

	"github.com/go-kure/kure/pkg/kubernetes/volsync"
)

func main() {
	obj := volsync.CreateReplicationSource("db-backup", "data")
	fmt.Println(obj.Kind, obj.Namespace+"/"+obj.Name)
}
Output:
ReplicationSource data/db-backup
Example (Modify)
package main

import (
	"fmt"

	volsyncv1alpha1 "github.com/backube/volsync/api/v1alpha1"

	"github.com/go-kure/kure/pkg/kubernetes/volsync"
)

func main() {
	rs := volsync.CreateReplicationSource("db-backup", "data")

	rs.Spec.Paused = false
	rs.Spec.Trigger = &volsyncv1alpha1.ReplicationSourceTriggerSpec{Manual: "go"}
	fmt.Println(rs.Spec.Trigger.Manual)
}
Output:
go
Example (Restic)
package main

import (
	"fmt"

	volsyncv1alpha1 "github.com/backube/volsync/api/v1alpha1"
	"k8s.io/utils/ptr"

	"github.com/go-kure/kure/pkg/kubernetes/volsync"
)

func main() {
	rs := volsync.CreateReplicationSource("db-backup", "data")
	rs.Spec = volsyncv1alpha1.ReplicationSourceSpec{
		SourcePVC: "postgres-data",
		Trigger:   &volsyncv1alpha1.ReplicationSourceTriggerSpec{Schedule: ptr.To("@hourly")},
		Restic: &volsyncv1alpha1.ReplicationSourceResticSpec{
			Repository: "restic-creds",
			ReplicationSourceVolumeOptions: volsyncv1alpha1.ReplicationSourceVolumeOptions{
				CopyMethod: volsync.CopyMethodSnapshot,
			},
			Retain: &volsyncv1alpha1.ResticRetainPolicy{
				Daily:   ptr.To[int32](7),
				Weekly:  ptr.To[int32](4),
				Monthly: ptr.To[int32](12),
			},
		},
	}
	fmt.Println(rs.Spec.SourcePVC, *rs.Spec.Trigger.Schedule, rs.Spec.Restic.CopyMethod)
}
Output:
postgres-data @hourly Snapshot

Types

type CopyMethod

type CopyMethod = volsyncv1alpha1.CopyMethodType

CopyMethod re-exports the upstream CopyMethodType for caller convenience.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL