From 444a47ab4cc3e648c58e925610ec86f6ef12a70b Mon Sep 17 00:00:00 2001 From: Simon Beck Date: Mon, 13 May 2024 13:26:56 +0200 Subject: [PATCH] Add docs Signed-off-by: Simon Beck --- docs/modules/ROOT/pages/how-tos/backup.adoc | 61 ++++++++- .../modules/ROOT/pages/how-tos/schedules.adoc | 41 ++++++ .../ROOT/pages/references/api-reference.adoc | 125 ++++++++++++++++++ 3 files changed, 226 insertions(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/how-tos/backup.adoc b/docs/modules/ROOT/pages/how-tos/backup.adoc index 9002d9a45..a0647ff9b 100644 --- a/docs/modules/ROOT/pages/how-tos/backup.adoc +++ b/docs/modules/ROOT/pages/how-tos/backup.adoc @@ -159,4 +159,63 @@ spec: secret: secretName: client-tls defaultMode: 420 ----- \ No newline at end of file +---- + +== Customize Pod Spec +You can override most of the fields in the podSpec for the backup jobs. + +These are the fields you can't override: + +* image +* command +* container name +* args + +The podSpec has to be created via a separate object of the type `PodConfig`. +Any annotations and labels set on the `PodConfig` will also be applied to the pod. +Any fields on the `PodConfig` object has precedence over settings specified in the job. +For example, if the job has `podSecurityContext` set and the `PodConfig` has it set as well, then the setting from the `PodConfig` will override the setting in the job definition. + +[source,yaml] +---- +apiVersion: k8up.io/v1 +kind: PodConfig +metadata: + name: podconfig + namespace: prod + annotations: + test: test +spec: + template: + spec: + containers: + - env: + - name: FOO + value: bar + securityContext: + allowPrivilegeEscalation: true +--- +apiVersion: k8up.io/v1 +kind: Backup +metadata: + name: k8up-backup + namespace: prod +spec: + failedJobsHistoryLimit: 1 + successfulJobsHistoryLimit: 1 + backend: + repoPasswordSecretRef: + name: backup-repo + key: password + s3: + endpoint: http://minio.minio-e2e.svc.cluster.local:9000 + bucket: backup + accessKeyIDSecretRef: + name: backup-credentials + key: username + secretAccessKeySecretRef: + name: backup-credentials + key: password + podConfig: + name: podconfig +---- diff --git a/docs/modules/ROOT/pages/how-tos/schedules.adoc b/docs/modules/ROOT/pages/how-tos/schedules.adoc index f86fb58bd..01493b35b 100644 --- a/docs/modules/ROOT/pages/how-tos/schedules.adoc +++ b/docs/modules/ROOT/pages/how-tos/schedules.adoc @@ -14,3 +14,44 @@ The file above will instruct the Operator to do backups every 5 minute, prune th Feel free to adjust the frequencies to your liking. To help you with the crontab syntax, we recommend to check out https://crontab.guru[crontab.guru]. TIP: You can always check the state and configuration of your backup by using `kubectl describe schedule`. By default, all PVCs are backed up automatically. Adding the annotation `k8up.io/backup=false` to a PVC object will exclude it from all following backups. Alternatively, you can set the environment variable `BACKUP_SKIP_WITHOUT_ANNOTATION=true` if you want K8up to ignore objects without the annotation. + +== Customize Pod Spec +Just like for each job type, it's possible to pass custom pod specs to a schedule. + +You can either set a `PodConfig` for all jobs in a schedule at once, or for each job individually. +The `PodConfig` set in the job has precedence over the one in the schedule. + +[source,yaml] +---- +apiVersion: k8up.io/v1 +kind: PodConfig +metadata: + name: podconfig + namespace: prod + annotations: + test: test +spec: + template: + spec: + containers: + - env: + - name: FOO + value: bar + securityContext: + allowPrivilegeEscalation: true +--- +apiVersion: k8up.io/v1 +kind: Schedule +metadata: + name: schedule-test + namespace: prod +spec: + podConfigRef: + name: podconfig + backend: + # Abridged for readability + backup: + # Abridged for readability + podConfig: + name: anotherPodConfig +---- diff --git a/docs/modules/ROOT/pages/references/api-reference.adoc b/docs/modules/ROOT/pages/references/api-reference.adoc index 233a24572..f68819b9f 100644 --- a/docs/modules/ROOT/pages/references/api-reference.adoc +++ b/docs/modules/ROOT/pages/references/api-reference.adoc @@ -23,6 +23,8 @@ TIP: A more sophisticated documentation is available under https://doc.crds.dev/ - xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-backuplist[$$BackupList$$] - xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-check[$$Check$$] - xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-checklist[$$CheckList$$] +- xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-podconfig[$$PodConfig$$] +- xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-podconfiglist[$$PodConfigList$$] - xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-prebackuppod[$$PreBackupPod$$] - xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-prebackuppodlist[$$PreBackupPodList$$] - xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-prune[$$Prune$$] @@ -235,6 +237,10 @@ BackupSchedule manages schedules for the backup service | *`backend`* __xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-backend[$$Backend$$]__ | Backend contains the restic repo where the job should backup to. | *`resources`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#resourcerequirements-v1-core[$$ResourceRequirements$$]__ | Resources describes the compute resource requirements (cpu, memory, etc.) | *`podSecurityContext`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#podsecuritycontext-v1-core[$$PodSecurityContext$$]__ | PodSecurityContext describes the security context with which this action shall be executed. +| *`podConfigRef`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#localobjectreference-v1-core[$$LocalObjectReference$$]__ | PodConfigRef describes the pod spec with wich this action shall be executed. +It takes precedence over the Resources or PodSecurityContext field. +It does not allow changing the image or the command of the resulting pod. +This is for advanced use-cases only. Please only set this if you know what you're doing. | *`volumes`* __xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-runnablevolumespec[$$RunnableVolumeSpec$$]__ | Volumes List of volumes that can be mounted by containers belonging to the pod. | *`activeDeadlineSeconds`* __integer__ | ActiveDeadlineSeconds specifies the duration in seconds relative to the startTime that the job may be continuously active before the system tries to terminate it. Value must be positive integer if given. @@ -273,6 +279,10 @@ ensure that the defaults are applied before creating the object on the API. | *`backend`* __xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-backend[$$Backend$$]__ | Backend contains the restic repo where the job should backup to. | *`resources`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#resourcerequirements-v1-core[$$ResourceRequirements$$]__ | Resources describes the compute resource requirements (cpu, memory, etc.) | *`podSecurityContext`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#podsecuritycontext-v1-core[$$PodSecurityContext$$]__ | PodSecurityContext describes the security context with which this action shall be executed. +| *`podConfigRef`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#localobjectreference-v1-core[$$LocalObjectReference$$]__ | PodConfigRef describes the pod spec with wich this action shall be executed. +It takes precedence over the Resources or PodSecurityContext field. +It does not allow changing the image or the command of the resulting pod. +This is for advanced use-cases only. Please only set this if you know what you're doing. | *`volumes`* __xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-runnablevolumespec[$$RunnableVolumeSpec$$]__ | Volumes List of volumes that can be mounted by containers belonging to the pod. | *`activeDeadlineSeconds`* __integer__ | ActiveDeadlineSeconds specifies the duration in seconds relative to the startTime that the job may be continuously active before the system tries to terminate it. Value must be positive integer if given. @@ -349,6 +359,10 @@ CheckSchedule manages the schedules for the checks | *`backend`* __xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-backend[$$Backend$$]__ | Backend contains the restic repo where the job should backup to. | *`resources`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#resourcerequirements-v1-core[$$ResourceRequirements$$]__ | Resources describes the compute resource requirements (cpu, memory, etc.) | *`podSecurityContext`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#podsecuritycontext-v1-core[$$PodSecurityContext$$]__ | PodSecurityContext describes the security context with which this action shall be executed. +| *`podConfigRef`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#localobjectreference-v1-core[$$LocalObjectReference$$]__ | PodConfigRef describes the pod spec with wich this action shall be executed. +It takes precedence over the Resources or PodSecurityContext field. +It does not allow changing the image or the command of the resulting pod. +This is for advanced use-cases only. Please only set this if you know what you're doing. | *`volumes`* __xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-runnablevolumespec[$$RunnableVolumeSpec$$]__ | Volumes List of volumes that can be mounted by containers belonging to the pod. | *`activeDeadlineSeconds`* __integer__ | ActiveDeadlineSeconds specifies the duration in seconds relative to the startTime that the job may be continuously active before the system tries to terminate it. Value must be positive integer if given. @@ -382,6 +396,10 @@ information. | *`backend`* __xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-backend[$$Backend$$]__ | Backend contains the restic repo where the job should backup to. | *`resources`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#resourcerequirements-v1-core[$$ResourceRequirements$$]__ | Resources describes the compute resource requirements (cpu, memory, etc.) | *`podSecurityContext`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#podsecuritycontext-v1-core[$$PodSecurityContext$$]__ | PodSecurityContext describes the security context with which this action shall be executed. +| *`podConfigRef`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#localobjectreference-v1-core[$$LocalObjectReference$$]__ | PodConfigRef describes the pod spec with wich this action shall be executed. +It takes precedence over the Resources or PodSecurityContext field. +It does not allow changing the image or the command of the resulting pod. +This is for advanced use-cases only. Please only set this if you know what you're doing. | *`volumes`* __xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-runnablevolumespec[$$RunnableVolumeSpec$$]__ | Volumes List of volumes that can be mounted by containers belonging to the pod. | *`activeDeadlineSeconds`* __integer__ | ActiveDeadlineSeconds specifies the duration in seconds relative to the startTime that the job may be continuously active before the system tries to terminate it. Value must be positive integer if given. @@ -468,6 +486,31 @@ KeepJobs is used property is not specified. |=== +[id="{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-jobobject"] +=== JobObject (interface{GetActiveDeadlineSeconds() *int64; GetPodConfig(context.Context, sigs.k8s.io/controller-runtime/pkg/client.Client) (*PodConfig, error); GetPodSecurityContext() *k8s.io/api/core/v1.PodSecurityContext; GetResources() k8s.io/api/core/v1.ResourceRequirements; GetStatus() Status; GetType() JobType; SetStatus(s Status); sigs.k8s.io/controller-runtime/pkg/client.Object}) + +JobObject is an interface that must be implemented by all CRDs that implement a job. + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-jobobjectlist[$$JobObjectList$$] +**** + + + + + +[id="{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-jobtype"] +=== JobType (string) + +JobType defines what job type this is. + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-effectiveschedule[$$EffectiveSchedule$$] +**** + + [id="{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-localspec"] === LocalSpec @@ -506,6 +549,66 @@ More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api- |=== +[id="{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-podconfig"] +=== PodConfig + +PodConfig is the Schema for the PodConcig API +Any annotations and labels set on this object will also be set on +the final pod. + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-podconfiglist[$$PodConfigList$$] +**** + +[cols="25a,75a", options="header"] +|=== +| Field | Description +| *`apiVersion`* __string__ | `k8up.io/v1` +| *`kind`* __string__ | `PodConfig` +| *`metadata`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#objectmeta-v1-meta[$$ObjectMeta$$]__ | Refer to Kubernetes API documentation for fields of `metadata`. + +| *`spec`* __xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-podconfigspec[$$PodConfigSpec$$]__ | +|=== + + +[id="{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-podconfiglist"] +=== PodConfigList + +SnapshotList contains a list of Snapshot + + + +[cols="25a,75a", options="header"] +|=== +| Field | Description +| *`apiVersion`* __string__ | `k8up.io/v1` +| *`kind`* __string__ | `PodConfigList` +| *`metadata`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#listmeta-v1-meta[$$ListMeta$$]__ | Refer to Kubernetes API documentation for fields of `metadata`. + +| *`items`* __xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-podconfig[$$PodConfig$$] array__ | +|=== + + +[id="{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-podconfigspec"] +=== PodConfigSpec + +PodConfigSpec contains the podTemplate definition. + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-podconfig[$$PodConfig$$] +**** + +[cols="25a,75a", options="header"] +|=== +| Field | Description +| *`template`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#podtemplatespec-v1-core[$$PodTemplateSpec$$]__ | +|=== + + + + [id="{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-prebackuppod"] === PreBackupPod @@ -621,6 +724,10 @@ PruneSchedule manages the schedules for the prunes | *`backend`* __xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-backend[$$Backend$$]__ | Backend contains the restic repo where the job should backup to. | *`resources`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#resourcerequirements-v1-core[$$ResourceRequirements$$]__ | Resources describes the compute resource requirements (cpu, memory, etc.) | *`podSecurityContext`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#podsecuritycontext-v1-core[$$PodSecurityContext$$]__ | PodSecurityContext describes the security context with which this action shall be executed. +| *`podConfigRef`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#localobjectreference-v1-core[$$LocalObjectReference$$]__ | PodConfigRef describes the pod spec with wich this action shall be executed. +It takes precedence over the Resources or PodSecurityContext field. +It does not allow changing the image or the command of the resulting pod. +This is for advanced use-cases only. Please only set this if you know what you're doing. | *`volumes`* __xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-runnablevolumespec[$$RunnableVolumeSpec$$]__ | Volumes List of volumes that can be mounted by containers belonging to the pod. | *`activeDeadlineSeconds`* __integer__ | ActiveDeadlineSeconds specifies the duration in seconds relative to the startTime that the job may be continuously active before the system tries to terminate it. Value must be positive integer if given. @@ -654,6 +761,10 @@ retention policies. | *`backend`* __xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-backend[$$Backend$$]__ | Backend contains the restic repo where the job should backup to. | *`resources`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#resourcerequirements-v1-core[$$ResourceRequirements$$]__ | Resources describes the compute resource requirements (cpu, memory, etc.) | *`podSecurityContext`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#podsecuritycontext-v1-core[$$PodSecurityContext$$]__ | PodSecurityContext describes the security context with which this action shall be executed. +| *`podConfigRef`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#localobjectreference-v1-core[$$LocalObjectReference$$]__ | PodConfigRef describes the pod spec with wich this action shall be executed. +It takes precedence over the Resources or PodSecurityContext field. +It does not allow changing the image or the command of the resulting pod. +This is for advanced use-cases only. Please only set this if you know what you're doing. | *`volumes`* __xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-runnablevolumespec[$$RunnableVolumeSpec$$]__ | Volumes List of volumes that can be mounted by containers belonging to the pod. | *`activeDeadlineSeconds`* __integer__ | ActiveDeadlineSeconds specifies the duration in seconds relative to the startTime that the job may be continuously active before the system tries to terminate it. Value must be positive integer if given. @@ -765,6 +876,10 @@ RestoreSchedule manages schedules for the restore service | *`backend`* __xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-backend[$$Backend$$]__ | Backend contains the restic repo where the job should backup to. | *`resources`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#resourcerequirements-v1-core[$$ResourceRequirements$$]__ | Resources describes the compute resource requirements (cpu, memory, etc.) | *`podSecurityContext`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#podsecuritycontext-v1-core[$$PodSecurityContext$$]__ | PodSecurityContext describes the security context with which this action shall be executed. +| *`podConfigRef`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#localobjectreference-v1-core[$$LocalObjectReference$$]__ | PodConfigRef describes the pod spec with wich this action shall be executed. +It takes precedence over the Resources or PodSecurityContext field. +It does not allow changing the image or the command of the resulting pod. +This is for advanced use-cases only. Please only set this if you know what you're doing. | *`volumes`* __xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-runnablevolumespec[$$RunnableVolumeSpec$$]__ | Volumes List of volumes that can be mounted by containers belonging to the pod. | *`activeDeadlineSeconds`* __integer__ | ActiveDeadlineSeconds specifies the duration in seconds relative to the startTime that the job may be continuously active before the system tries to terminate it. Value must be positive integer if given. @@ -803,6 +918,10 @@ one you need to define an existing PVC. | *`backend`* __xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-backend[$$Backend$$]__ | Backend contains the restic repo where the job should backup to. | *`resources`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#resourcerequirements-v1-core[$$ResourceRequirements$$]__ | Resources describes the compute resource requirements (cpu, memory, etc.) | *`podSecurityContext`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#podsecuritycontext-v1-core[$$PodSecurityContext$$]__ | PodSecurityContext describes the security context with which this action shall be executed. +| *`podConfigRef`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#localobjectreference-v1-core[$$LocalObjectReference$$]__ | PodConfigRef describes the pod spec with wich this action shall be executed. +It takes precedence over the Resources or PodSecurityContext field. +It does not allow changing the image or the command of the resulting pod. +This is for advanced use-cases only. Please only set this if you know what you're doing. | *`volumes`* __xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-runnablevolumespec[$$RunnableVolumeSpec$$]__ | Volumes List of volumes that can be mounted by containers belonging to the pod. | *`activeDeadlineSeconds`* __integer__ | ActiveDeadlineSeconds specifies the duration in seconds relative to the startTime that the job may be continuously active before the system tries to terminate it. Value must be positive integer if given. @@ -871,6 +990,10 @@ RunnableSpec defines the fields that are necessary on the specs of all actions t | *`backend`* __xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-backend[$$Backend$$]__ | Backend contains the restic repo where the job should backup to. | *`resources`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#resourcerequirements-v1-core[$$ResourceRequirements$$]__ | Resources describes the compute resource requirements (cpu, memory, etc.) | *`podSecurityContext`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#podsecuritycontext-v1-core[$$PodSecurityContext$$]__ | PodSecurityContext describes the security context with which this action shall be executed. +| *`podConfigRef`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#localobjectreference-v1-core[$$LocalObjectReference$$]__ | PodConfigRef describes the pod spec with wich this action shall be executed. +It takes precedence over the Resources or PodSecurityContext field. +It does not allow changing the image or the command of the resulting pod. +This is for advanced use-cases only. Please only set this if you know what you're doing. | *`volumes`* __xref:{anchor_prefix}-github-com-k8up-io-k8up-v2-api-v1-runnablevolumespec[$$RunnableVolumeSpec$$]__ | Volumes List of volumes that can be mounted by containers belonging to the pod. | *`activeDeadlineSeconds`* __integer__ | ActiveDeadlineSeconds specifies the duration in seconds relative to the startTime that the job may be continuously active before the system tries to terminate it. Value must be positive integer if given. @@ -1034,6 +1157,8 @@ KeepJobs is used property is not specified. KeepJobs is used property is not specified. | *`resourceRequirementsTemplate`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#resourcerequirements-v1-core[$$ResourceRequirements$$]__ | ResourceRequirementsTemplate describes the compute resource requirements (cpu, memory, etc.) | *`podSecurityContext`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#podsecuritycontext-v1-core[$$PodSecurityContext$$]__ | PodSecurityContext describes the security context with which actions (such as backups) shall be executed. +| *`podConfigRef`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#localobjectreference-v1-core[$$LocalObjectReference$$]__ | PodConfigRef will apply the given template to all job definitions in this Schedule. +It can be overriden for specific jobs if necessary. |===