(Documentation) Update ArangoDeploymentReplication and ArangoLocalStorage CR auto-generated docs (#1455)

CHANGELOG.md

@@ -9,7 +9,9 @@
 - (Documentation) Update ArangoDeployment CR auto-generated docs
 - (Documentation) Update ArangoBackup and ArangoBackupPolicy CR auto-generated docs
 - (Bugfix) Fix missing Pod Status case in the RuntimeContainerImageUpdateAction
+- (Documentation) Update ArangoDeploymentReplication and ArangoLocalStorage CR auto-generated docs
 - (Feature) Member Memory Reservation
+- (Documentation) Update ArangoDeploymentReplication and ArangoLocalStorage CR auto-generated docs
 
 ## [1.2.34](https://github.com/arangodb/kube-arangodb/tree/1.2.34) (2023-10-16)
 - (Bugfix) Fix make manifests-crd-file command

docs/api/ArangoDeploymentReplication.V1.md

@@ -0,0 +1,106 @@
+# API Reference for ArangoDeploymentReplication V1
+
+## Spec
+
+### .spec.cancellation.ensureInSync: bool
+
+EnsureInSync if it is true then during cancellation process data consistency is required.
+Default value is true.
+
+[Code Reference](/pkg/apis/replication/v1/replication_spec.go#L38)
+
+### .spec.cancellation.sourceReadOnly: bool
+
+SourceReadOnly if it true then after cancellation source data center should be in read-only mode.
+Default value is false.
+
+[Code Reference](/pkg/apis/replication/v1/replication_spec.go#L41)
+
+### .spec.destination.auth.keyfileSecretName: string
+
+KeyfileSecretName holds the name of a Secret containing a client authentication
+certificate formatted at keyfile in a `tls.keyfile` field.
+If `userSecretName` has not been set,
+the client authentication certificate found in the secret with this name is also used to configure
+the synchronization and fetch the synchronization status.
+
+[Code Reference](/pkg/apis/replication/v1/endpoint_authentication_spec.go#L37)
+
+### .spec.destination.auth.userSecretName: string
+
+UserSecretName holds the name of a Secret containing a `username` & `password`
+field used for basic authentication.
+The user identified by the username must have write access in the `_system` database
+of the ArangoDB cluster at the endpoint.
+
+[Code Reference](/pkg/apis/replication/v1/endpoint_authentication_spec.go#L42)
+
+### .spec.destination.deploymentName: string
+
+DeploymentName holds the name of an ArangoDeployment resource.
+If set, this provides default values for masterEndpoint, auth & tls.
+
+[Code Reference](/pkg/apis/replication/v1/endpoint_spec.go#L36)
+
+### .spec.destination.masterEndpoint: []string
+
+MasterEndpoint holds a list of URLs used to reach the syncmaster(s)
+Use this setting if the source cluster is not running inside a Kubernetes cluster
+that is reachable from the Kubernetes cluster the `ArangoDeploymentReplication` resource is deployed in.
+Specifying this setting and `deploymentName` at the same time is not allowed.
+
+Default Value: []
+
+[Code Reference](/pkg/apis/replication/v1/endpoint_spec.go#L42)
+
+### .spec.destination.tls.caSecretName: string
+
+CASecretName holds the name of a Secret containing a ca.crt public key for TLS validation.
+This setting is required, unless `deploymentName` has been set.
+
+[Code Reference](/pkg/apis/replication/v1/endpoint_tls_spec.go#L34)
+
+### .spec.source.auth.keyfileSecretName: string
+
+KeyfileSecretName holds the name of a Secret containing a client authentication
+certificate formatted at keyfile in a `tls.keyfile` field.
+If `userSecretName` has not been set,
+the client authentication certificate found in the secret with this name is also used to configure
+the synchronization and fetch the synchronization status.
+
+[Code Reference](/pkg/apis/replication/v1/endpoint_authentication_spec.go#L37)
+
+### .spec.source.auth.userSecretName: string
+
+UserSecretName holds the name of a Secret containing a `username` & `password`
+field used for basic authentication.
+The user identified by the username must have write access in the `_system` database
+of the ArangoDB cluster at the endpoint.
+
+[Code Reference](/pkg/apis/replication/v1/endpoint_authentication_spec.go#L42)
+
+### .spec.source.deploymentName: string
+
+DeploymentName holds the name of an ArangoDeployment resource.
+If set, this provides default values for masterEndpoint, auth & tls.
+
+[Code Reference](/pkg/apis/replication/v1/endpoint_spec.go#L36)
+
+### .spec.source.masterEndpoint: []string
+
+MasterEndpoint holds a list of URLs used to reach the syncmaster(s)
+Use this setting if the source cluster is not running inside a Kubernetes cluster
+that is reachable from the Kubernetes cluster the `ArangoDeploymentReplication` resource is deployed in.
+Specifying this setting and `deploymentName` at the same time is not allowed.
+
+Default Value: []
+
+[Code Reference](/pkg/apis/replication/v1/endpoint_spec.go#L42)
+
+### .spec.source.tls.caSecretName: string
+
+CASecretName holds the name of a Secret containing a ca.crt public key for TLS validation.
+This setting is required, unless `deploymentName` has been set.
+
+[Code Reference](/pkg/apis/replication/v1/endpoint_tls_spec.go#L34)
+

docs/api/ArangoLocalStorage.V1Alpha.md

@@ -0,0 +1,66 @@
+# API Reference for ArangoLocalStorage V1Alpha
+
+## Spec
+
+### .spec.localPath: []string
+
+LocalPath setting specifies one or more local directories (on the nodes) used to create persistent volumes in.
+
+[Code Reference](/pkg/apis/storage/v1alpha/local_storage_spec.go#L36)
+
+### .spec.nodeSelector: map[string]string
+
+NodeSelector setting specifies which nodes the operator will provision persistent volumes on.
+
+[Code Reference](/pkg/apis/storage/v1alpha/local_storage_spec.go#L43)
+
+### .spec.podCustomization.priority: int32
+
+Priority if defined, sets the priority for pods of storage provisioner
+
+[Code Reference](/pkg/apis/storage/v1alpha/local_storage_pod_customization.go#L25)
+
+### .spec.privileged: bool
+
+Privileged if set, passes Privileged flag to SecurityContext for pods of storage provisioner
+
+[Code Reference](/pkg/apis/storage/v1alpha/local_storage_spec.go#L45)
+
+### .spec.storageClass.isDefault: bool
+
+IsDefault setting specifies if the created `StorageClass` will
+be marked as default storage class.
+
+Default Value: false
+
+[Code Reference](/pkg/apis/storage/v1alpha/storage_class_spec.go#L42)
+
+### .spec.storageClass.name: string
+
+Name setting specifies the name of the storage class that
+created `PersistentVolume` will use.
+If empty, this field defaults to the name of the `ArangoLocalStorage` object.
+If a `StorageClass` with given name does not yet exist, it will be created.
+
+Default Value: ""
+
+[Code Reference](/pkg/apis/storage/v1alpha/storage_class_spec.go#L38)
+
+### .spec.storageClass.reclaimPolicy: core.PersistentVolumeReclaimPolicy
+
+ReclaimPolicy defines what happens to a persistent volume when released from its claim.
+
+Links:
+* [Documentation of core.PersistentVolumeReclaimPolicy](https://kubernetes.io/docs/concepts/storage/persistent-volumes#reclaiming)
+
+[Code Reference](/pkg/apis/storage/v1alpha/storage_class_spec.go#L46)
+
+### .spec.tolerations: []core.Toleration
+
+Tolerations specifies the tolerations added to pods of storage provisioner
+
+Links:
+* [Documentation of core.Toleration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#toleration-v1-core)
+
+[Code Reference](/pkg/apis/storage/v1alpha/local_storage_spec.go#L41)
+

docs/api/README.md

@@ -3,5 +3,7 @@
  - [ArangoBackup.V1](./ArangoBackup.V1.md)
  - [ArangoBackupPolicy.V1](./ArangoBackupPolicy.V1.md)
  - [ArangoDeployment.V1](./ArangoDeployment.V1.md)
+ - [ArangoDeploymentReplication.V1](./ArangoDeploymentReplication.V1.md)
+ - [ArangoLocalStorage.V1Alpha](./ArangoLocalStorage.V1Alpha.md)
  - [ArangoMember.V1](./ArangoMember.V1.md)
 

docs/deployment-replication-resource-reference.md

@@ -2,6 +2,7 @@
 
 #### Enterprise Edition only
 
+[Full CustomResourceDefinition reference ->](./api/ArangoDeploymentReplication.V1.md)
 
 The ArangoDB Replication Operator creates and maintains ArangoDB
 `arangosync` configurations in a Kubernetes cluster, given a replication specification.
@@ -183,95 +184,6 @@ running in Kubernetes:
    As soon as the replication is configured, the `Add collection` button in the `Collections`
    page of the web interface (of the destination cluster) will be grayed out.
 
-## Specification reference
-
-Below you'll find all settings of the `ArangoDeploymentReplication` custom resource.
-
-### `spec.source.deploymentName: string`
-
-This setting specifies the name of an `ArangoDeployment` resource that runs a cluster
-with sync enabled.
-
-This cluster configured as the replication source.
-
-### `spec.source.masterEndpoint: []string`
-
-This setting specifies zero or more master endpoint URLs of the source cluster.
-
-Use this setting if the source cluster is not running inside a Kubernetes cluster
-that is reachable from the Kubernetes cluster the `ArangoDeploymentReplication` resource is deployed in.
-
-Specifying this setting and `spec.source.deploymentName` at the same time is not allowed.
-
-### `spec.source.auth.keyfileSecretName: string`
-
-This setting specifies the name of a `Secret` containing a client authentication certificate called `tls.keyfile` used to authenticate
-with the SyncMaster at the specified source.
-
-If `spec.source.auth.userSecretName` has not been set,
-the client authentication certificate found in the secret with this name is also used to configure
-the synchronization and fetch the synchronization status.
-
-This setting is required.
-
-### `spec.source.auth.userSecretName: string`
-
-This setting specifies the name of a `Secret` containing a `username` & `password` used to authenticate
-with the SyncMaster at the specified source in order to configure synchronization and fetch synchronization status.
-
-The user identified by the username must have write access in the `_system` database of the source ArangoDB cluster.
-
-### `spec.source.tls.caSecretName: string`
-
-This setting specifies the name of a `Secret` containing a TLS CA certificate `ca.crt` used to verify
-the TLS connection created by the SyncMaster at the specified source.
-
-This setting is required, unless `spec.source.deploymentName` has been set.
-
-### `spec.destination.deploymentName: string`
-
-This setting specifies the name of an `ArangoDeployment` resource that runs a cluster
-with sync enabled.
-
-This cluster configured as the replication destination.
-
-### `spec.destination.masterEndpoint: []string`
-
-This setting specifies zero or more master endpoint URLs of the destination cluster.
-
-Use this setting if the destination cluster is not running inside a Kubernetes cluster
-that is reachable from the Kubernetes cluster the `ArangoDeploymentReplication` resource is deployed in.
-
-Specifying this setting and `spec.destination.deploymentName` at the same time is not allowed.
-
-### `spec.destination.auth.keyfileSecretName: string`
-
-This setting specifies the name of a `Secret` containing a client authentication certificate called `tls.keyfile` used to authenticate
-with the SyncMaster at the specified destination.
-
-If `spec.destination.auth.userSecretName` has not been set,
-the client authentication certificate found in the secret with this name is also used to configure
-the synchronization and fetch the synchronization status.
-
-This setting is required, unless `spec.destination.deploymentName` or `spec.destination.auth.userSecretName` has been set.
-
-Specifying this setting and `spec.destination.userSecretName` at the same time is not allowed.
-
-### `spec.destination.auth.userSecretName: string`
-
-This setting specifies the name of a `Secret` containing a `username` & `password` used to authenticate
-with the SyncMaster at the specified destination in order to configure synchronization and fetch synchronization status.
-
-The user identified by the username must have write access in the `_system` database of the destination ArangoDB cluster.
-
-Specifying this setting and `spec.destination.keyfileSecretName` at the same time is not allowed.
-
-### `spec.destination.tls.caSecretName: string`
-
-This setting specifies the name of a `Secret` containing a TLS CA certificate `ca.crt` used to verify
-the TLS connection created by the SyncMaster at the specified destination.
-
-This setting is required, unless `spec.destination.deploymentName` has been set.
 
 ## Authentication details
 

docs/storage-resource.md

@@ -1,5 +1,7 @@
 # ArangoLocalStorage Custom Resource
 
+[Full CustomResourceDefinition reference ->](./api/ArangoLocalStorage.V1Alpha.md)
+
 The ArangoDB Storage Operator creates and maintains ArangoDB
 storage resources in a Kubernetes cluster, given a storage specification.
 This storage specification is a `CustomResource` following
@@ -31,33 +33,3 @@ This definition results in:
 
 The provisioned volumes will have a capacity that matches
 the requested capacity of volume claims.
-
-## Specification reference
-
-Below you'll find all settings of the `ArangoLocalStorage` custom resource.
-
-### `spec.storageClass.name: string`
-
-This setting specifies the name of the storage class that
-created `PersistentVolume` will use.
-
-If empty, this field defaults to the name of the `ArangoLocalStorage`
-object.
-
-If a `StorageClass` with given name does not yet exist, it
-will be created.
-
-### `spec.storageClass.isDefault: bool`
-
-This setting specifies if the created `StorageClass` will
-be marked as default storage class. (default is `false`)
-
-### `spec.localPath: stringList`
-
-This setting specifies one of more local directories
-(on the nodes) used to create persistent volumes in.
-
-### `spec.nodeSelector: nodeSelector`
-
-This setting specifies which nodes the operator will
-provision persistent volumes on.

internal/docs_test.go

@@ -40,6 +40,8 @@ import (
 
 	backupApi "github.com/arangodb/kube-arangodb/pkg/apis/backup/v1"
 	deploymentApi "github.com/arangodb/kube-arangodb/pkg/apis/deployment/v1"
+	replicationApi "github.com/arangodb/kube-arangodb/pkg/apis/replication/v1"
+	storageApi "github.com/arangodb/kube-arangodb/pkg/apis/storage/v1alpha"
 	"github.com/arangodb/kube-arangodb/pkg/util"
 )
 
@@ -167,6 +169,16 @@ func Test_GenerateAPIDocs(t *testing.T) {
 				"Status": backupApi.ArangoBackupPolicy{}.Status,
 			},
 		},
+		fmt.Sprintf("%s/pkg/apis/replication/v1", root): {
+			"ArangoDeploymentReplication.V1": {
+				"Spec": replicationApi.ArangoDeploymentReplication{}.Spec,
+			},
+		},
+		fmt.Sprintf("%s/pkg/apis/storage/v1alpha", root): {
+			"ArangoLocalStorage.V1Alpha": {
+				"Spec": storageApi.ArangoLocalStorage{}.Spec,
+			},
+		},
 	}
 
 	resultPaths := make(map[string]string)

pkg/apis/replication/v1/endpoint_authentication_spec.go

@@ -31,6 +31,9 @@ import (
 type EndpointAuthenticationSpec struct {
 	// KeyfileSecretName holds the name of a Secret containing a client authentication
 	// certificate formatted at keyfile in a `tls.keyfile` field.
+	// If `userSecretName` has not been set,
+	// the client authentication certificate found in the secret with this name is also used to configure
+	// the synchronization and fetch the synchronization status.
 	KeyfileSecretName *string `json:"keyfileSecretName,omitempty"`
 	// UserSecretName holds the name of a Secret containing a `username` & `password`
 	// field used for basic authentication.

pkg/apis/replication/v1/endpoint_spec.go

@@ -32,9 +32,13 @@ import (
 // in either source or destination mode.
 type EndpointSpec struct {
 	// DeploymentName holds the name of an ArangoDeployment resource.
-	// If set this provides default values for masterEndpoint, auth & tls.
+	// If set, this provides default values for masterEndpoint, auth & tls.
 	DeploymentName *string `json:"deploymentName,omitempty"`
-	// MasterEndpoint holds a list of URLs used to reach the syncmaster(s).
+	// MasterEndpoint holds a list of URLs used to reach the syncmaster(s)
+	// Use this setting if the source cluster is not running inside a Kubernetes cluster
+	// that is reachable from the Kubernetes cluster the `ArangoDeploymentReplication` resource is deployed in.
+	// Specifying this setting and `deploymentName` at the same time is not allowed.
+	// +doc/default: []
 	MasterEndpoint []string `json:"masterEndpoint,omitempty"`
 	// Authentication holds settings needed to authentication at the syncmaster.
 	Authentication EndpointAuthenticationSpec `json:"auth"`

pkg/apis/replication/v1/endpoint_tls_spec.go

@@ -30,6 +30,7 @@ import (
 // in either source or destination endpoint.
 type EndpointTLSSpec struct {
 	// CASecretName holds the name of a Secret containing a ca.crt public key for TLS validation.
+	// This setting is required, unless `deploymentName` has been set.
 	CASecretName *string `json:"caSecretName,omitempty"`
 }
 

pkg/apis/replication/v1/replication_spec.go

@@ -1,7 +1,7 @@
 //
 // DISCLAIMER
 //
-// Copyright 2016-2022 ArangoDB GmbH, Cologne, Germany
+// Copyright 2016-2023 ArangoDB GmbH, Cologne, Germany
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

pkg/apis/storage/v1alpha/local_storage_pod_customization.go

@@ -1,7 +1,7 @@
 //
 // DISCLAIMER
 //
-// Copyright 2016-2022 ArangoDB GmbH, Cologne, Germany
+// Copyright 2016-2023 ArangoDB GmbH, Cologne, Germany
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -21,6 +21,7 @@
 package v1alpha
 
 type LocalStoragePodCustomization struct {
+	// Priority if defined, sets the priority for pods of storage provisioner
 	Priority *int32 `json:"priority,omitempty"`
 }
 

pkg/apis/storage/v1alpha/local_storage_spec.go

@@ -1,7 +1,7 @@
 //
 // DISCLAIMER
 //
-// Copyright 2016-2022 ArangoDB GmbH, Cologne, Germany
+// Copyright 2016-2023 ArangoDB GmbH, Cologne, Germany
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -32,10 +32,16 @@ import (
 // an ArangoLocalStorage.
 type LocalStorageSpec struct {
 	StorageClass StorageClassSpec `json:"storageClass"`
+	// LocalPath setting specifies one or more local directories (on the nodes) used to create persistent volumes in.
 	LocalPath []string `json:"localPath,omitempty"`
 
+	// Tolerations specifies the tolerations added to pods of storage provisioner
+	// +doc/type: []core.Toleration
+	// +doc/link: Documentation of core.Toleration|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#toleration-v1-core
 	Tolerations []core.Toleration `json:"tolerations,omitempty"`
+	// NodeSelector setting specifies which nodes the operator will provision persistent volumes on.
 	NodeSelector map[string]string `json:"nodeSelector,omitempty"`
+	// Privileged if set, passes Privileged flag to SecurityContext for pods of storage provisioner
 	Privileged *bool `json:"privileged,omitempty"`
 
 	PodCustomization *LocalStoragePodCustomization `json:"podCustomization,omitempty"`

pkg/apis/storage/v1alpha/storage_class_spec.go

@@ -30,8 +30,19 @@ import (
 
 // StorageClassSpec contains specification for create StorageClass.
 type StorageClassSpec struct {
+	// Name setting specifies the name of the storage class that
+	// created `PersistentVolume` will use.
+	// If empty, this field defaults to the name of the `ArangoLocalStorage` object.
+	// If a `StorageClass` with given name does not yet exist, it will be created.
+	// +doc/default: ""
 	Name string `json:"name,omitempty"`
+	// IsDefault setting specifies if the created `StorageClass` will
+	// be marked as default storage class.
+	// +doc/default: false
 	IsDefault bool `json:"isDefault,omitempty"`
+	// ReclaimPolicy defines what happens to a persistent volume when released from its claim.
+	// +doc/type: core.PersistentVolumeReclaimPolicy
+	// +doc/link: Documentation of core.PersistentVolumeReclaimPolicy|https://kubernetes.io/docs/concepts/storage/persistent-volumes#reclaiming
 	ReclaimPolicy *core.PersistentVolumeReclaimPolicy `json:"reclaimPolicy,omitempty"`
 }