crd.md

Operator Custom Resource Reference Guide

Custom resources are extensions of the Kubernetes API.

A resource is an endpoint in the Kubernetes API that stores a collection of API objects of a certain kind; for example, the built-in pods resource contains a collection of Pod objects. A Custom Resource is an extension of the Kubernetes API, many core Kubernetes functions are now built using custom resources, making Kubernetes more modular. Cluster admins can update custom resources independently of the cluster itself. Once a custom resource is installed, users can create and access its objects using kubectl, just as they do for built-in resources like Pods.

The CustomResourceDefinition API resource allows you to define custom resources. Defining a CRD object creates a new custom resource with a name and schema that you specify. The Kubernetes API serves and handles the storage of your custom resource. Every resource is build from KGV that stands for Group Version Resource and this is what drives the Kubernetes API Server structure. The OpensearchCLuster CRD is representing an Opensearch cluster.

Our CRD is Defined by kind: OpenSearchCluster,group: opensearch.opster.io and version v1.

Name	Type	Description	Required
apiVersion	string	opensearch.opster.io/v1	true
kind	string	OpenSearchCluster	true
metadata	object	Refer to the Kubernetes API documentation for the fields of the `metadata` field.	true
spec	object	ClusterSpec defines the desired state of OpenSearchSpec	true
status	object	OpensearchClusterStatus defines the observed state of ClusterStatus. include ComponentsStatus that saves and share necessary state of the operator components.	true

OpensearchCluster.spec

ClusterSpec defines the desired state of OpensearchCluster

Name	Type	Description	Required
general	object	Opensearch general configuration	true
Bootstrap	object	Bootstrap pod configuration	false
Dashboards	object	Opensearch-dashboards configuration	false
confMgmt	object	Config object to enable additional OpensearchOperator features/components	false
security	object	Defined security reconciler configuration	false
nodePools	[]object	List of objects that define the different nodePools in an OpensearchCluster. Each nodePool represents a group of nodes with the same opensearch roles and resources. Each nodePool is deployed as a Kubernetes StatefulSet. Together they form the opensearch cluster.	true
monitoring	object	monitoring configuration in an OpensearchCluster	false
initHelper	object	InitHelper image configuration	false

GeneralConfig

GeneralConfig defines global Opensearch cluster configuration

Name	Type	Description	Required	default
httpPort	int32	http exposure port	false	9200
vendor	string	Vendor distribution to use for the cluster, currently only opensearch is supported	false	opensearch
command	string	Specify command in case you want to override the default command, useful if you have a custom image.	false	./opensearch-docker-entrypoint.sh
version	string	Version of opensearch to deploy	false	latest
ServiceAccount	string	k8s service account name	false	cluster name
ServiceName	string	Name to use for the k8s service to expose the cluster internally	false	cluster name
SetVMMaxMapCount	bool	will add VMmaxMapCount	false
additionalConfig	string	Added extra items to opensearch.yml	string
annotations	map[string]string	Adds support for annotations in services	false
labels	map[string]string	add user defined labels to nodePool	false	-
env	[]corev1.Env	add user defined environment variables to nodePool	false	-
DefaultRepo	string	Default image repository to use
keystore	[]opsterv1.KeystoreValue	List of objects that define secret values that will populate the opensearch keystore.	false	-
pluginsList	[]string	List of plugins that should be installed for OpenSearch at startup.	false	[]
podSecurityContext	*corev1.PodSecurityContext	Set the security context for the cluster pods.	false	-
securityContext	*corev1.SecurityContext	Set the security context for the cluster pods' containers.	false	-
snapshotRepositories	[]SnapshotRepoConfig	Snapshot Repo settings	false	-
additionalVolumes	[]object	List of additional volume mounts	false	-

Bootstrap

Bootstrap defines Opensearch bootstrap pod configuration

Name	Type	Description	Required	default
resources	corev1.ResourceRequirements	Define Opensearch bootstrap pod resources	false	-
tolerations	[]corev1.Toleration	add toleration to bootstrap pod	false	-
nodeSelector	map[string]string	Add NodeSelector to bootstrap pod	false	-
affinity	corev1.Affinity	add affinity to bootstrap pod	false	-
jvm	string	JVM args. Use this to define heap size	false	-Xmx512M -Xms512M
additionalConfig	string	Added extra items to opensearch.yml in the bootstrap pod	map[string]string	general.additionalConfig

Dashboards

Dashboards defines Opensearch-Dashboard configuration and deployment

Name	Type	Description	Required	default
enable	bool	if true, will deploy Opensearch-dashboards with the cluster	false	false
replicas	int	defines Opensearch-Dashboards deployment's replicas	true	1
basePath	string	Defines the base path of opensearch dashboards (e.g. when using a reverse proxy)	false	-
resources	corev1.ResourceRequirements	Define Opensearch-Dashboard resources	false	Default Opensearch-dashboard resources
version	string	Opensearch-dashboards version	false	latest
Tls	DashboardsTlsConfig	defining Dashbaord TLS configuration	false	false
env	[]corev1.Env	add user defined environment variables to dashboard app	false	-
image	string	Define Opensearch-dashboards image	false	-
imagePullPolicy	corev1.PullPolicy	Define Opensearch-dashboards image pull policy	false	-
imagePullSecrets	corev1.LocalObjectReference	Define Opensearch-dashboards image pull secrets	false	-
tolerations	[]corev1.Toleration	Adds toleration to dashboard pods	false	-
nodeSelector	map[string]string	Adds NodeSelector to dashboard pods	false	-
affinity	corev1.Affinity	Adds affinity to dashboard pods	false	-
labels	map[string]string	Adds labels to dashboard pods	false	-
annotations	map[string]string	Adds annotations to dashboard pods	false	-
service	opsterv1.DashboardsService	Customize dashboard service	false	-
pluginsList	[]string	List of plugins that should be installed for OpenSearch Dashboards at startup.	false	[]
podSecurityContext	*corev1.PodSecurityContext	Set the security context for the dashboards pods.	false	-
securityContext	*corev1.SecurityContext	Set the security context for the dashboards pods' containers.	false	-

NodePools

Every NodePool is defining different Opensearch Nodes StatefulSet

Name	Type	Description	Required	default
component	string	statefulset name - will create $cluster-name-$component STS	true	-
replicas	int	defines NodePool deployment's replicas	true	1
diskSize	string	nodePool data disk size	true	-
NodeSelector	map[string]string	add NodeSelector to nodePool	false	-
Tls	DashboardsTlsConfig	defining Dashbaord TLS configuration	false	false
resources	corev1.ResourceRequirements	Define NodePool resources	false
roles	[]string	List of OpenSearch roles to assign to the nodePool	true	-
JVM	string	JVM args. Use this to define heap size (recommendation: Set to half of memory request)	false	Half of `resources.requests.memory` if jvm is not set. Fallback value is `-Xmx512M -Xms512M` if neither `resources.requests.memory` nor jvm are set.
Affinity	corev1.Affinity	add affinity to nodePool	false	-
Tolerations	[]corev1.Toleration	add toleration to nodePool	false	-
topologySpreadConstraints	[]corev1.TopologySpreadConstraint	add topology spread contraints to nodePool	false	-
annotations	map[string]string	Adds annotations to node pods	false	-
priorityClassName	string	Adds a priority class to nodes	false	-
probes	ProbesConfig	Updates the probes timeouts and thresholds config	false	-

InitHelperConfig

InitHelperConfig defines global Opensearch InitHelper image configuration

Name	Type	Description	Required	default
image	string	Define InitHelper image	false	docker.io/busybox
imagePullPolicy	corev1.PullPolicy	Define InitHelper image pull policy	false	-
resources	corev1.ResourceRequirements	Define initcontainer resorces	false	-
version	string	Version of InitHelper (busybox) image to deploy	false	1.27.2-buildx

Monitoring

Monitoring defines Opensearch monitoring configuration

Name	Type	Description	Required	default
enable	bool	Define if to enable monitoring for that cluster	true	-
labels	map[string]string	Add LabelsSelector to ServiceMonitor	false	-
monitoringUserSecret	[]string	Define from which user the monitor will run (Getting Secret name, the secret should contain 'username':'password' fileds).	false	admin
scrapeInterval	string	Define interval for scraping	false	30s
pluginURL	string	Define offline link to Aiven Plugin	false	https://github.com/aiven/prometheus-exporter-plugin-for-opensearch/releases/download//prometheus-exporter-.zip/
tlsConfig	map[]	Tls Configuration See tlsConfig below	false	-

Monitoring.tlsConfig

Monitoring TLS configuration options

Name	Type	Description	Required	default
serverName	string	Used to verify the hostname for the targets	false
insecureSkipVerify	bool	Disable target certificate validation	false	false

Keystore

Every Keystore Value defines a secret to pull secrets from.

Name	Type	Description	Required	default
secret	corev1.LocalObjectReference	Define secret that contains key value pairs	true	-
keyMappings	map	Define key mappings from secret to keystore entry. Example: "old: new" creates a keystore entry "new" with the value from the secret entry "old". When a map is provided, only the specified keys are loaded from the secret, so use "key: key" to load a key that should not be renamed.	false	-

AdditionalVolume

AdditionalVolume object define additional volume and volumeMount

Name	Type	Description	Required	default
name	string	Defines name for additional volume	true	-
path	string	Defines mount path for additional volume	true	-
subPath	string	key of the configmap or secret to use (mounts only that key at the given path), ignored for other volume types	false	-
restartPods	bool	Defines if pod should restar or not in case of change in VolumeSource object	false	false
emptyDir	corev1.EmptyDirVolumeSource	Defines emptyDir object to be mouted	false	-
configMap	corev1.ConfigMapVolumeSource	Defines ConfgMap object to be mounted	false	-
secret	corev1.SecretVolumeSource	Defines Secret object to be mounted	false	-
csi	corev1.CSIVolumeSource	Defines the CSI object to be mounted	false	-

ProbesConfig

ProbesConfig defines per nodepool probes thresholds and timeouts instead of defaults

Name	Type	Description	Required	default
liveness	ProbeConfig	Update liveness probe thresholds and timeouts	false	-
readiness	ReadinessProbeConfig	Update readiness probe thresholds and timeouts	false	-
startup	ProbeConfig	Update startup probe thresholds and timeouts	false	-

ProbeConfig

ProbeConfig defines per probe thresholds and timeouts instead of defaults

Name	Type	Description	Required	default
initialDelaySeconds	int32	Update probe's initialDelaySeconds	false	10
periodSeconds	int32	Update probe's periodSeconds	false	20
timeoutSeconds	int32	Update probe's timeoutSeconds	false	5
successThreshold	int32	Update probe's successThreshold	false	1
failureThreshold	int32	Update probe's failureThreshold	false	10

ReadinessProbeConfig

ReadinessProbeConfig defines per probe thresholds and timeouts instead of defaults

Name	Type	Description	Required	default
initialDelaySeconds	int32	Update probe's initialDelaySeconds	false	60
periodSeconds	int32	Update probe's periodSeconds	false	30
timeoutSeconds	int32	Update probe's timeoutSeconds	false	30
failureThreshold	int32	Update probe's failureThreshold	false	5