diff --git a/CHANGELOG.md b/CHANGELOG.md index 220d9352b..f288b4636 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/docs/api/ArangoDeploymentReplication.V1.md b/docs/api/ArangoDeploymentReplication.V1.md new file mode 100644 index 000000000..d1a693add --- /dev/null +++ b/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) + diff --git a/docs/api/ArangoLocalStorage.V1Alpha.md b/docs/api/ArangoLocalStorage.V1Alpha.md new file mode 100644 index 000000000..1ee3c209e --- /dev/null +++ b/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) + diff --git a/docs/api/README.md b/docs/api/README.md index 8ade4cb54..1de9a48e2 100644 --- a/docs/api/README.md +++ b/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) diff --git a/docs/deployment-replication-resource-reference.md b/docs/deployment-replication-resource-reference.md index c7f33962e..0462a6e3f 100644 --- a/docs/deployment-replication-resource-reference.md +++ b/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 diff --git a/docs/storage-resource.md b/docs/storage-resource.md index fb22dfe66..5d63da7e0 100644 --- a/docs/storage-resource.md +++ b/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. diff --git a/internal/docs_test.go b/internal/docs_test.go index 006fbabbc..dfb8080a6 100644 --- a/internal/docs_test.go +++ b/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) diff --git a/pkg/apis/replication/v1/endpoint_authentication_spec.go b/pkg/apis/replication/v1/endpoint_authentication_spec.go index 85bbbd4c7..e3520dcff 100644 --- a/pkg/apis/replication/v1/endpoint_authentication_spec.go +++ b/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. diff --git a/pkg/apis/replication/v1/endpoint_spec.go b/pkg/apis/replication/v1/endpoint_spec.go index 701b1a6ff..b6c95356b 100644 --- a/pkg/apis/replication/v1/endpoint_spec.go +++ b/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"` diff --git a/pkg/apis/replication/v1/endpoint_tls_spec.go b/pkg/apis/replication/v1/endpoint_tls_spec.go index 6b75f31c0..641480e41 100644 --- a/pkg/apis/replication/v1/endpoint_tls_spec.go +++ b/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"` } diff --git a/pkg/apis/replication/v1/replication_spec.go b/pkg/apis/replication/v1/replication_spec.go index 846cb3a55..bdcfaba34 100644 --- a/pkg/apis/replication/v1/replication_spec.go +++ b/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. diff --git a/pkg/apis/storage/v1alpha/local_storage_pod_customization.go b/pkg/apis/storage/v1alpha/local_storage_pod_customization.go index b0667a58e..9826ded95 100644 --- a/pkg/apis/storage/v1alpha/local_storage_pod_customization.go +++ b/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"` } diff --git a/pkg/apis/storage/v1alpha/local_storage_spec.go b/pkg/apis/storage/v1alpha/local_storage_spec.go index 28b7a1c16..e68663588 100644 --- a/pkg/apis/storage/v1alpha/local_storage_spec.go +++ b/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,11 +32,17 @@ import ( // an ArangoLocalStorage. type LocalStorageSpec struct { StorageClass StorageClassSpec `json:"storageClass"` - LocalPath []string `json:"localPath,omitempty"` + // LocalPath setting specifies one or more local directories (on the nodes) used to create persistent volumes in. + LocalPath []string `json:"localPath,omitempty"` - Tolerations []core.Toleration `json:"tolerations,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 *bool `json:"privileged,omitempty"` + // Privileged if set, passes Privileged flag to SecurityContext for pods of storage provisioner + Privileged *bool `json:"privileged,omitempty"` PodCustomization *LocalStoragePodCustomization `json:"podCustomization,omitempty"` } diff --git a/pkg/apis/storage/v1alpha/storage_class_spec.go b/pkg/apis/storage/v1alpha/storage_class_spec.go index 4f6faf4d5..a0f6682d9 100644 --- a/pkg/apis/storage/v1alpha/storage_class_spec.go +++ b/pkg/apis/storage/v1alpha/storage_class_spec.go @@ -30,8 +30,19 @@ import ( // StorageClassSpec contains specification for create StorageClass. type StorageClassSpec struct { - Name string `json:"name,omitempty"` - IsDefault bool `json:"isDefault,omitempty"` + // 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"` }