VolSync Builders

VolSync Builders - ReplicationSource and ReplicationDestination

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

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

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.

Related Packages

• kubernetes-builders — broader resource builder family
• stack — domain model that produces Kubernetes resources
• Builder contract: release 2 migration notes — the retired config-struct layer, field by field