diff --git a/.wordlist.txt b/.wordlist.txt index e9676af..c4f8554 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -1,11 +1,21 @@ Azurite BarmanObjectStore +BarmanObjectStoreConfiguration BarmanObjectStores CloudNativePG +EnvVar Gi IfNotPresent +InstanceSidecarConfiguration MinIO +ObjectMeta +ObjectStore +ObjectStoreSpec +ObjectStoreStatus PITR +RecoveryWindow +RetentionPolicy +ServerRecoveryWindow TLS TODO WAL @@ -26,6 +36,7 @@ cnpg codebase csi customresourcedefinition +devel externalClusters gcs gf @@ -37,6 +48,7 @@ io isWALArchiver kubectl kubernetes +md minio namespace namespaces @@ -47,12 +59,15 @@ postgresql primaryUpdateStrategy rbac rc +recoverability repos +retentionCheckInterval rolebinding sc selfsigned serverName serviceaccount +sig storageClass tfddg tgz diff --git a/README.md b/README.md index 9ba83ec..6950975 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,7 @@ plugin for [CloudNativePG](https://cloudnative-pg.io/). - [Backup](#backup) - [Restore](#restore) - [Replica clusters](#replica-clusters) +- [API Reference](#api-reference) ## Features @@ -335,3 +336,8 @@ spec: parameters: barmanObjectName: minio-store-b ``` + +## API Reference + +You can find the API reference on its +[dedicated page](./docs/src/plugin-barman-cloud.v1.md). diff --git a/Taskfile.yml b/Taskfile.yml index 35f1fc0..913bdc9 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -69,6 +69,22 @@ tasks: sources: - ./** + apidoc: + desc: Update the API Reference section of the documentation + env: + # renovate: datasource=git-refs depName=genref lookupName=https://github.com/cloudnative-pg/daggerverse currentValue=main + DAGGER_APIDOC_SHA: ac27cc7677fc42ea129fd3c1aa2b2894aad3a246 + cmds: + - GITHUB_REF= dagger -s call -m github.com/cloudnative-pg/daggerverse/genref@${DAGGER_APIDOC_SHA} genref --source . + --args "-c=config.yaml" --args "-o=src" --args "-include=plugin-barman-cloud" + file --path src/plugin-barman-cloud.v1.md + export --path docs/src/plugin-barman-cloud.v1.md + sources: + - ./api/**/*.go + - ./docs/config.yaml + generates: + - ./docs/src/plugin-barman-cloud.v1.md + go-test: desc: Run go test env: diff --git a/api/v1/objectstore_types.go b/api/v1/objectstore_types.go index 786d92d..a028adf 100644 --- a/api/v1/objectstore_types.go +++ b/api/v1/objectstore_types.go @@ -48,6 +48,7 @@ type ObjectStoreSpec struct { // +optional RetentionPolicy string `json:"retentionPolicy,omitempty"` + // The configuration for the sidecar that runs in the instance pods // +optional InstanceSidecarConfiguration InstanceSidecarConfiguration `json:"instanceSidecarConfiguration,omitempty"` } @@ -81,7 +82,12 @@ type ObjectStore struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata"` + // Specification of the desired behavior of the ObjectStore. + // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status Spec ObjectStoreSpec `json:"spec"` + // Most recently observed status of the ObjectStore. This data may not be up to + // date. Populated by the system. Read-only. + // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status // +optional Status ObjectStoreStatus `json:"status,omitempty"` } diff --git a/config/crd/bases/barmancloud.cnpg.io_objectstores.yaml b/config/crd/bases/barmancloud.cnpg.io_objectstores.yaml index c505399..3dc7451 100644 --- a/config/crd/bases/barmancloud.cnpg.io_objectstores.yaml +++ b/config/crd/bases/barmancloud.cnpg.io_objectstores.yaml @@ -37,7 +37,9 @@ spec: metadata: type: object spec: - description: ObjectStoreSpec defines the desired state of ObjectStore. + description: |- + Specification of the desired behavior of the ObjectStore. + More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status properties: configuration: description: The configuration for the barman-cloud tool suite @@ -381,8 +383,8 @@ spec: - destinationPath type: object instanceSidecarConfiguration: - description: InstanceSidecarConfiguration defines the configuration - for the sidecar that runs in the instance pods. + description: The configuration for the sidecar that runs in the instance + pods properties: env: description: The environment to be explicitly passed to the sidecar @@ -523,7 +525,10 @@ spec: - configuration type: object status: - description: ObjectStoreStatus defines the observed state of ObjectStore. + description: |- + Most recently observed status of the ObjectStore. This data may not be up to + date. Populated by the system. Read-only. + More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status properties: serverRecoveryWindow: additionalProperties: diff --git a/docs/config.yaml b/docs/config.yaml new file mode 100644 index 0000000..4195d1a --- /dev/null +++ b/docs/config.yaml @@ -0,0 +1,24 @@ +hiddenMemberFields: + - "TypeMeta" + +externalPackages: + - match: ^k8s\.io/(api|apimachinery/pkg/apis)/ + target: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#{{- lower .TypeIdentifier -}}-{{- arrIndex .PackageSegments -1 -}}-{{- arrIndex .PackageSegments -2 -}} + - match: ^github\.com/cloudnative-pg/barman-cloud + target: https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api/#{{- .TypeIdentifier }} + +hideTypePatterns: + - "ParseError$" + - "\\.ObjectStoreList$" + +markdownDisabled: false + +stripPrefix: + - k8s.io/api/ + - k8s.io/apimachinery/pkg/apis/ + +apis: + - name: plugin-barman-cloud + title: API Reference + package: github.com/cloudnative-pg/plugin-barman-cloud + path: api/v1 diff --git a/docs/markdown/members.tpl b/docs/markdown/members.tpl new file mode 100644 index 0000000..d3bacd1 --- /dev/null +++ b/docs/markdown/members.tpl @@ -0,0 +1,34 @@ +{{ define "members" }} + {{- /* . is a apiType */ -}} + {{- range .GetMembers -}} + {{- /* . is a apiMember */ -}} + {{- if not .Hidden }} +{{ .FieldName }} + {{- if and (not .IsOptional) (not .IsInline) }} [Required]{{- end -}} +
+{{/* Link for type reference */}} + {{- with .GetType -}} + {{- if .Link -}} +{{ .DisplayName }} + {{- else -}} +{{ .DisplayName }} + {{- end -}} + {{- end }} + + + {{- if .IsInline -}} +(Members of {{ .FieldName }} are embedded into this type.) + {{- end }} + {{ if .GetComment -}} + {{ .GetComment }} + {{- else -}} + No description provided. + {{- end }} + {{- if and (eq (.GetType.Name.Name) "ObjectMeta") -}} +Refer to the Kubernetes API documentation for the fields of the metadata field. + {{- end -}} + + + {{- end }} + {{- end }} +{{ end }} diff --git a/docs/markdown/pkg.tpl b/docs/markdown/pkg.tpl new file mode 100644 index 0000000..345d032 --- /dev/null +++ b/docs/markdown/pkg.tpl @@ -0,0 +1,43 @@ +{{ define "packages" -}} + +# API Reference + +{{ $grpname := "" -}} +{{- range $idx, $val := .packages -}} + {{- if and (ne .GroupName "") (eq $grpname "") -}} +{{ .GetComment -}} +{{- $grpname = .GroupName -}} + {{- end -}} +{{- end }} + +## Resource Types + +{{ range .packages -}} + {{- /* if ne .GroupName "" */ -}} + {{- range .VisibleTypes -}} + {{- if .IsExported }} +- [{{ .DisplayName }}]({{ .Link }}) + {{- end -}} + {{- end -}} + {{- /* end */ -}} +{{- end -}} + +{{- range .packages -}} + {{- if ne .GroupName "" -}} + + {{- /* For package with a group name, list all type definitions in it. */ -}} + {{- range .VisibleTypes -}} + {{- if or .Referenced .IsExported -}} +{{ template "type" . }} + {{- end -}} + {{- end }} + {{- else -}} + {{- /* For package w/o group name, list only types referenced. */ -}} + {{- range .VisibleTypes -}} + {{- if .Referenced -}} +{{ template "type" . }} + {{- end -}} + {{- end }} + {{- end }} +{{- end }} +{{- end }} diff --git a/docs/markdown/type.tpl b/docs/markdown/type.tpl new file mode 100644 index 0000000..91f7621 --- /dev/null +++ b/docs/markdown/type.tpl @@ -0,0 +1,37 @@ +{{ define "type" }} + +## {{ .Name.Name }} {#{{ .Anchor }}} + +{{ if eq .Kind "Alias" -}} +(Alias of `{{ .Underlying }}`) +{{ end }} + +{{- with .References }} +**Appears in:** +{{ range . }} +{{ if or .Referenced .IsExported -}} +- [{{ .DisplayName }}]({{ .Link }}) +{{ end -}} +{{- end -}} +{{- end }} + +{{ if .GetComment -}} +{{ .GetComment }} +{{ end }} +{{ if .GetMembers -}} + + + + {{- /* . is a apiType */ -}} + {{- if .IsExported -}} +{{- /* Add apiVersion and kind rows if deemed necessary */}} + + + {{- end -}} + +{{/* The actual list of members is in the following template */}} +{{- template "members" . -}} + +
FieldDescription
apiVersion [Required]
string		{{- .APIGroup -}}
kind [Required]
string		{{- .Name.Name -}}
+{{- end -}} +{{- end -}} diff --git a/docs/src/plugin-barman-cloud.v1.md b/docs/src/plugin-barman-cloud.v1.md new file mode 100644 index 0000000..0573d8f --- /dev/null +++ b/docs/src/plugin-barman-cloud.v1.md @@ -0,0 +1,179 @@ +# API Reference + +

Package v1 contains API Schema definitions for the barmancloud v1 API group

+ + +## Resource Types + + +- [ObjectStore](#barmancloud-cnpg-io-v1-ObjectStore) + +## ObjectStore {#barmancloud-cnpg-io-v1-ObjectStore} + + + +

ObjectStore is the Schema for the objectstores API.

+ + + + + + + + + + + + + + + + + +
FieldDescription
apiVersion [Required]
string		barmancloud.cnpg.io/v1
kind [Required]
string		ObjectStore
metadata [Required]
+meta/v1.ObjectMeta +		 + No description provided.Refer to the Kubernetes API documentation for the fields of the metadata field.
spec [Required]
+ObjectStoreSpec +		 +

Specification of the desired behavior of the ObjectStore. +More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status

+
status
+ObjectStoreStatus +		 +

Most recently observed status of the ObjectStore. This data may not be up to +date. Populated by the system. Read-only. +More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status

+
+ +## InstanceSidecarConfiguration {#barmancloud-cnpg-io-v1-InstanceSidecarConfiguration} + + +**Appears in:** + +- [ObjectStoreSpec](#barmancloud-cnpg-io-v1-ObjectStoreSpec) + + +

InstanceSidecarConfiguration defines the configuration for the sidecar that runs in the instance pods.

+ + + + + + + + + + + + +
FieldDescription
env
+[]core/v1.EnvVar +		 +

The environment to be explicitly passed to the sidecar

+
retentionPolicyIntervalSeconds
+int +		 +

The retentionCheckInterval defines the frequency at which the +system checks and enforces retention policies.

+
+ +## ObjectStoreSpec {#barmancloud-cnpg-io-v1-ObjectStoreSpec} + + +**Appears in:** + +- [ObjectStore](#barmancloud-cnpg-io-v1-ObjectStore) + + +

ObjectStoreSpec defines the desired state of ObjectStore.

+ + + + + + + + + + + + + + + +
FieldDescription
configuration [Required]
+github.com/cloudnative-pg/barman-cloud/pkg/api.BarmanObjectStoreConfiguration +		 +

The configuration for the barman-cloud tool suite

+
retentionPolicy
+string +		 +

RetentionPolicy is the retention policy to be used for backups +and WALs (i.e. '60d'). The retention policy is expressed in the form +of XXu where XX is a positive integer and u is in [dwm] - +days, weeks, months.

+
instanceSidecarConfiguration
+InstanceSidecarConfiguration +		 +

The configuration for the sidecar that runs in the instance pods

+
+ +## ObjectStoreStatus {#barmancloud-cnpg-io-v1-ObjectStoreStatus} + + +**Appears in:** + +- [ObjectStore](#barmancloud-cnpg-io-v1-ObjectStore) + + +

ObjectStoreStatus defines the observed state of ObjectStore.

+ + + + + + + + + +
FieldDescription
serverRecoveryWindow [Required]
+map[string]RecoveryWindow +		 +

ServerRecoveryWindow maps each server to its recovery window

+
+ +## RecoveryWindow {#barmancloud-cnpg-io-v1-RecoveryWindow} + + +**Appears in:** + +- [ObjectStoreStatus](#barmancloud-cnpg-io-v1-ObjectStoreStatus) + + +

RecoveryWindow represents the time span between the first +recoverability point and the last successful backup of a PostgreSQL +server, defining the period during which data can be restored.

+ + + + + + + + + + + + +
FieldDescription
firstRecoverabilityPoint [Required]
+meta/v1.Time +		 +

The first recoverability point in a PostgreSQL server refers to +the earliest point in time to which the database can be +restored.

+
lastSuccussfulBackupTime [Required]
+meta/v1.Time +		 +

The last successful backup time

+
\ No newline at end of file diff --git a/manifest.yaml b/manifest.yaml index f77efc6..2240f77 100644 --- a/manifest.yaml +++ b/manifest.yaml @@ -36,7 +36,9 @@ spec: metadata: type: object spec: - description: ObjectStoreSpec defines the desired state of ObjectStore. + description: |- + Specification of the desired behavior of the ObjectStore. + More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status properties: configuration: description: The configuration for the barman-cloud tool suite @@ -380,8 +382,8 @@ spec: - destinationPath type: object instanceSidecarConfiguration: - description: InstanceSidecarConfiguration defines the configuration - for the sidecar that runs in the instance pods. + description: The configuration for the sidecar that runs in the instance + pods properties: env: description: The environment to be explicitly passed to the sidecar @@ -522,7 +524,10 @@ spec: - configuration type: object status: - description: ObjectStoreStatus defines the observed state of ObjectStore. + description: |- + Most recently observed status of the ObjectStore. This data may not be up to + date. Populated by the system. Read-only. + More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status properties: serverRecoveryWindow: additionalProperties: