[Docs] Add docs for DeploymentSpec (#1363)

Author: nikita-vanyasin

docs/api/ArangoDeployment.V1.md

@@ -29,6 +29,13 @@ import (
 	"github.com/arangodb/kube-arangodb/pkg/apis/shared"
 )
 
+// ArangoDeploymentArchitecture defines the list of supported architectures.
+// Possible values are:
+// - `amd64`: Use processors with the x86-64 architecture.
+// - `arm64`: Use processors with the 64-bit ARM architecture.
+// The setting expects a list of strings, but you should only specify a single list item for the architecture, except when you want to migrate from one architecture to the other.
+// The first list item defines the new default architecture for the deployment that you want to migrate to.
+// To use the ARM architecture, you need to enable it in the operator first using --set "operator.architectures={amd64,arm64}". See Installation with Helm.
 type ArangoDeploymentArchitecture []ArangoDeploymentArchitectureType
 
 func (a ArangoDeploymentArchitecture) GetDefault() ArangoDeploymentArchitectureType {

pkg/apis/deployment/v1/architecture.go

@@ -0,0 +1,83 @@
+//
+// DISCLAIMER
+//
+// Copyright 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.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// Copyright holder is ArangoDB GmbH, Cologne, Germany
+//
+
+package v1
+
+import core "k8s.io/api/core/v1"
+
+// DeploymentCommunicationMethod define communication method used for inter-cluster communication
+type DeploymentCommunicationMethod string
+
+const (
+	// DefaultDeploymentCommunicationMethod define default communication method.
+	DefaultDeploymentCommunicationMethod = DeploymentCommunicationMethodHeadlessService
+	// DeploymentCommunicationMethodHeadlessService define old communication mechanism, based on headless service.
+	DeploymentCommunicationMethodHeadlessService DeploymentCommunicationMethod = "headless"
+	// DeploymentCommunicationMethodDNS define ClusterIP Service DNS based communication.
+	DeploymentCommunicationMethodDNS DeploymentCommunicationMethod = "dns"
+	// DeploymentCommunicationMethodShortDNS define ClusterIP Service DNS based communication. Use namespaced short DNS (used in migration)
+	DeploymentCommunicationMethodShortDNS DeploymentCommunicationMethod = "short-dns"
+	// DeploymentCommunicationMethodHeadlessDNS define Headless Service DNS based communication.
+	DeploymentCommunicationMethodHeadlessDNS DeploymentCommunicationMethod = "headless-dns"
+	// DeploymentCommunicationMethodIP define ClusterIP Service IP based communication.
+	DeploymentCommunicationMethodIP DeploymentCommunicationMethod = "ip"
+)
+
+// Get returns communication method from pointer. If pointer is nil default is returned.
+func (d *DeploymentCommunicationMethod) Get() DeploymentCommunicationMethod {
+	if d == nil {
+		return DefaultDeploymentCommunicationMethod
+	}
+
+	switch v := *d; v {
+	case DeploymentCommunicationMethodHeadlessService, DeploymentCommunicationMethodDNS, DeploymentCommunicationMethodIP, DeploymentCommunicationMethodShortDNS, DeploymentCommunicationMethodHeadlessDNS:
+		return v
+	default:
+		return DefaultDeploymentCommunicationMethod
+	}
+}
+
+// ServiceType returns Service Type for communication method
+func (d *DeploymentCommunicationMethod) ServiceType() core.ServiceType {
+	switch d.Get() {
+	default:
+		return core.ServiceTypeClusterIP
+	}
+}
+
+// ServiceClusterIP returns Service ClusterIP for communication method
+func (d *DeploymentCommunicationMethod) ServiceClusterIP() string {
+	switch d.Get() {
+	case DeploymentCommunicationMethodHeadlessDNS:
+		return core.ClusterIPNone
+	default:
+		return ""
+	}
+}
+
+// String returns string representation of method.
+func (d DeploymentCommunicationMethod) String() string {
+	return string(d)
+}
+
+// New returns pointer.
+func (d DeploymentCommunicationMethod) New() *DeploymentCommunicationMethod {
+	return &d
+}

pkg/apis/deployment/v1/deployment_communication_method.go

@@ -30,19 +30,30 @@ import (
 
 // ExternalAccessSpec holds configuration for the external access provided for the deployment.
 type ExternalAccessSpec struct {
-	// Type of external access
+
+	// Type specifies the type of Service that will be created to provide access to the ArangoDB deployment from outside the Kubernetes cluster.
+	// + doc/enum: Auto|Create a Service of type LoadBalancer and fallback to a Service or type NodePort when the LoadBalancer is not assigned an IP address.
+	// + doc/enum: None|limit access to application running inside the Kubernetes cluster.
+	// + doc/enum: LoadBalancer|Create a Service of type LoadBalancer for the ArangoDB deployment.
+	// + doc/enum: NodePort|Create a Service of type NodePort for the ArangoDB deployment.
 	Type *ExternalAccessType `json:"type,omitempty"`
-	// Optional port used in case of Auto or NodePort type.
+
+	// NodePort define optional port used in case of Auto or NodePort type.
 	NodePort *int `json:"nodePort,omitempty"`
-	// Optional IP used to configure a load-balancer on, in case of Auto or LoadBalancer type.
+
+	// LoadBalancerIP define optional IP used to configure a load-balancer on, in case of Auto or LoadBalancer type.
 	LoadBalancerIP *string `json:"loadBalancerIP,omitempty"`
+
+	// LoadBalancerSourceRanges define LoadBalancerSourceRanges used for LoadBalancer Service type
 	// If specified and supported by the platform, this will restrict traffic through the cloud-provider
 	// load-balancer will be restricted to the specified client IPs. This field will be ignored if the
 	// cloud-provider does not support the feature.
-	// More info: https://kubernetes.io/docs/tasks/access-application-cluster/configure-cloud-provider-firewall/
+	// +docs/link: Cloud Provider Firewall|https://kubernetes.io/docs/tasks/access-application-cluster/configure-cloud-provider-firewall/
 	LoadBalancerSourceRanges []string `json:"loadBalancerSourceRanges,omitempty"`
+
 	// AdvertisedEndpoint is passed to the coordinators/single servers for advertising a specific endpoint
 	AdvertisedEndpoint *string `json:"advertisedEndpoint,omitempty"`
+
 	// ManagedServiceNames keeps names of services which are not managed by KubeArangoDB.
 	// It is only relevant when type of service is `managed`.
 	ManagedServiceNames []string `json:"managedServiceNames,omitempty"`

pkg/apis/deployment/v1/deployment_spec.go

@@ -31,6 +31,7 @@ type StorageEngine string
 
 const (
 	// StorageEngineMMFiles yields a cluster using the mmfiles storage engine
+	// deprecated
 	StorageEngineMMFiles StorageEngine = "MMFiles"
 	// StorageEngineRocksDB yields a cluster using the rocksdb storage engine
 	StorageEngineRocksDB StorageEngine = "RocksDB"

pkg/apis/deployment/v1/external_access_spec.go

@@ -29,6 +29,13 @@ import (
 	"github.com/arangodb/kube-arangodb/pkg/apis/shared"
 )
 
+// ArangoDeploymentArchitecture defines the list of supported architectures.
+// Possible values are:
+// - `amd64`: Use processors with the x86-64 architecture.
+// - `arm64`: Use processors with the 64-bit ARM architecture.
+// The setting expects a list of strings, but you should only specify a single list item for the architecture, except when you want to migrate from one architecture to the other.
+// The first list item defines the new default architecture for the deployment that you want to migrate to.
+// To use the ARM architecture, you need to enable it in the operator first using --set "operator.architectures={amd64,arm64}". See Installation with Helm.
 type ArangoDeploymentArchitecture []ArangoDeploymentArchitectureType
 
 func (a ArangoDeploymentArchitecture) GetDefault() ArangoDeploymentArchitectureType {

pkg/apis/deployment/v1/storage_engine.go

@@ -0,0 +1,83 @@
+//
+// DISCLAIMER
+//
+// Copyright 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.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// Copyright holder is ArangoDB GmbH, Cologne, Germany
+//
+
+package v2alpha1
+
+import core "k8s.io/api/core/v1"
+
+// DeploymentCommunicationMethod define communication method used for inter-cluster communication
+type DeploymentCommunicationMethod string
+
+const (
+	// DefaultDeploymentCommunicationMethod define default communication method.
+	DefaultDeploymentCommunicationMethod = DeploymentCommunicationMethodHeadlessService
+	// DeploymentCommunicationMethodHeadlessService define old communication mechanism, based on headless service.
+	DeploymentCommunicationMethodHeadlessService DeploymentCommunicationMethod = "headless"
+	// DeploymentCommunicationMethodDNS define ClusterIP Service DNS based communication.
+	DeploymentCommunicationMethodDNS DeploymentCommunicationMethod = "dns"
+	// DeploymentCommunicationMethodShortDNS define ClusterIP Service DNS based communication. Use namespaced short DNS (used in migration)
+	DeploymentCommunicationMethodShortDNS DeploymentCommunicationMethod = "short-dns"
+	// DeploymentCommunicationMethodHeadlessDNS define Headless Service DNS based communication.
+	DeploymentCommunicationMethodHeadlessDNS DeploymentCommunicationMethod = "headless-dns"
+	// DeploymentCommunicationMethodIP define ClusterIP Service IP based communication.
+	DeploymentCommunicationMethodIP DeploymentCommunicationMethod = "ip"
+)
+
+// Get returns communication method from pointer. If pointer is nil default is returned.
+func (d *DeploymentCommunicationMethod) Get() DeploymentCommunicationMethod {
+	if d == nil {
+		return DefaultDeploymentCommunicationMethod
+	}
+
+	switch v := *d; v {
+	case DeploymentCommunicationMethodHeadlessService, DeploymentCommunicationMethodDNS, DeploymentCommunicationMethodIP, DeploymentCommunicationMethodShortDNS, DeploymentCommunicationMethodHeadlessDNS:
+		return v
+	default:
+		return DefaultDeploymentCommunicationMethod
+	}
+}
+
+// ServiceType returns Service Type for communication method
+func (d *DeploymentCommunicationMethod) ServiceType() core.ServiceType {
+	switch d.Get() {
+	default:
+		return core.ServiceTypeClusterIP
+	}
+}
+
+// ServiceClusterIP returns Service ClusterIP for communication method
+func (d *DeploymentCommunicationMethod) ServiceClusterIP() string {
+	switch d.Get() {
+	case DeploymentCommunicationMethodHeadlessDNS:
+		return core.ClusterIPNone
+	default:
+		return ""
+	}
+}
+
+// String returns string representation of method.
+func (d DeploymentCommunicationMethod) String() string {
+	return string(d)
+}
+
+// New returns pointer.
+func (d DeploymentCommunicationMethod) New() *DeploymentCommunicationMethod {
+	return &d
+}