Merge pull request #293 from cybozu-go/add-technical-note

KAIZEN: add comments explaining the developers' intent.

Author: skoya76

api/v1/mantlebackup_types.go

@@ -51,8 +51,11 @@ type MantleBackupStatus struct {
 	// 'snapSize' indicates SIZE of `rbd snap ls`
 	SnapSize *int64 `json:"snapSize,omitempty"`
 
-	// 'transferPartSize' indicates the size of each part of the data
-	// transferred from the primary to the secondary.
+	// 'transferPartSize' indicates the size of each part of the data transferred
+	// from the primary to the secondary.
+	// Some jobs read the part size from this field rather than directly from the
+	// mantle-controller command-line argument. This ensures that the part size
+	// does not change while these jobs for a given MantleBackup are running.
 	TransferPartSize *resource.Quantity `json:"transferPartSize,omitempty"`
 }
 

charts/mantle-cluster-wide/templates/mantle.cybozu.io_mantlebackups.yaml

@@ -142,8 +142,11 @@ spec:
                 - type: integer
                 - type: string
                 description: |-
-                  'transferPartSize' indicates the size of each part of the data
-                  transferred from the primary to the secondary.
+                  'transferPartSize' indicates the size of each part of the data transferred
+                  from the primary to the secondary.
+                  Some jobs read the part size from this field rather than directly from the
+                  mantle-controller command-line argument. This ensures that the part size
+                  does not change while these jobs for a given MantleBackup are running.
                 pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
                 x-kubernetes-int-or-string: true
             type: object

config/crd/bases/mantle.cybozu.io_mantlebackups.yaml

@@ -142,8 +142,11 @@ spec:
                 - type: integer
                 - type: string
                 description: |-
-                  'transferPartSize' indicates the size of each part of the data
-                  transferred from the primary to the secondary.
+                  'transferPartSize' indicates the size of each part of the data transferred
+                  from the primary to the secondary.
+                  Some jobs read the part size from this field rather than directly from the
+                  mantle-controller command-line argument. This ensures that the part size
+                  does not change while these jobs for a given MantleBackup are running.
                 pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
                 x-kubernetes-int-or-string: true
             type: object

internal/controller/mantlebackup_controller.go

@@ -1582,6 +1582,9 @@ func calculateExportDataPVCSize(transferPartSize *resource.Quantity) (*resource.
 		return nil, fmt.Errorf("failed to convert status.transferPartSize to int64: %s", transferPartSize.String())
 	}
 
+	// The margin of the PVC size accounts for the filesystem metadata overhead required in addition
+	// to the backup data itself. The lower bound prevents the metadata from taking up a disproportionately
+	// large share of the PVC when the backup data size is small.
 	if pvcSizeI64 < 512*1024*1024 {
 		pvcSizeI64 = 512 * 1024 * 1024
 	}

internal/controller/script/job-export.sh

@@ -60,6 +60,9 @@ write_endpoints
 if [ -e "/mantle/export-${PART_NUM}.bin" ]; then
     exit
 fi
+# The export-diff output is first saved to a temporary file and then renamed to the final file used for
+# uploading. This makes it easy to detect whether the job was interrupted during export-diff when the
+# export job is restarted after an interruption.
 rm -f /mantle/tmp.bin
 if [ -z "${FROM_SNAP_NAME}" ]; then
     rbd export-diff \