diff --git a/docs/server/kubernetes-operator/v1.3.0/README.md b/docs/server/kubernetes-operator/v1.3.0/README.md new file mode 100644 index 000000000..b8bb98676 --- /dev/null +++ b/docs/server/kubernetes-operator/v1.3.0/README.md @@ -0,0 +1,5 @@ +--- +# title is for breadcrumb and sidebar nav +title: Kubernetes Operator v1.3.0 +order: 1 +--- diff --git a/docs/server/kubernetes-operator/v1.3.0/getting-started/README.md b/docs/server/kubernetes-operator/v1.3.0/getting-started/README.md new file mode 100644 index 000000000..9d6a7d6a4 --- /dev/null +++ b/docs/server/kubernetes-operator/v1.3.0/getting-started/README.md @@ -0,0 +1,65 @@ +--- +order: 1 +dir: + text: "Getting started" + link: true + order: 1 +--- + + + +--- +Welcome to the **KurrentDB Kubernetes Operator** guide. In this guide, we’ll refer to the KurrentDB Kubernetes Operator simply as “the Operator.” Use the Operator to simplify backup, scaling, and upgrades of KurrentDB clusters on Kubernetes. + +:::important +The Operator is an Enterprise-only feature, please [contact us](https://www.kurrent.io/contact) for more information. +::: + +## Why run KurrentDB on Kubernetes? + +Kubernetes is the modern enterprise standard for deploying containerized applications at scale. The Operator streamlines deployment and management of KurrentDB clusters. + +## Features + +* Deploy single-node or multi-node clusters +* Back up and restore clusters +* Perform rolling upgrades and update configurations + +### New in 1.3.0 + +* Fix/improve support for resizing KurrentDB clusters, including explicitly handling data safety, + minimizing downtime, and allowing the user to cancel a resize operation that is not progressing. + See [Updating Replica Count](../operations/modify-deployments.md#updating-replica-count) for details. +* Support for custom labels and annotations on all child resources (StatefulSets, Pods, + LoadBalancers, etc). +* Allow users to use public certificate authorities like LetsEcrypt without having to manually pass + the publicly trusted cert in a secret. +* Allow manual overrides to the generated ConfigMap that is passed to KurrentDB. Previously, if a + user manually altered the ConfigMap it would get immediately overwritten, whereas now it will + "stick" until the next time the KurrentDB resource is updated. +* Fix a bug affecting the KurrentDBBackup behavior when cluster's fqdnTemplate met certain criteria. +* Fix and clarified the `credentialsSecretName` behavior in the helm chart. It is not normally + required at all, but in previous versions, it was generating warning events with the default + configuration. +* Update helm chart to support the normal `--skip-crds` mechanism. + +## Supported KurrentDB Versions + +The Operator supports running the following major versions of KurrentDB: +- v25.x +- v24.x +- v23.x + +## Supported Hardware Architectures + +The Operator is packaged for the following hardware architectures: +- x86_64 +- arm64 + +## Technical Support + +For support questions, please [contact us](https://www.kurrent.io/contact). + +## First Steps + +Ready to install? Head over to the [installation](installation.md) section. diff --git a/docs/server/kubernetes-operator/v1.3.0/getting-started/images/install/deployments-list.png b/docs/server/kubernetes-operator/v1.3.0/getting-started/images/install/deployments-list.png new file mode 100644 index 000000000..00a310c8d Binary files /dev/null and b/docs/server/kubernetes-operator/v1.3.0/getting-started/images/install/deployments-list.png differ diff --git a/docs/server/kubernetes-operator/v1.3.0/getting-started/images/install/logs.png b/docs/server/kubernetes-operator/v1.3.0/getting-started/images/install/logs.png new file mode 100644 index 000000000..fa207c732 Binary files /dev/null and b/docs/server/kubernetes-operator/v1.3.0/getting-started/images/install/logs.png differ diff --git a/docs/server/kubernetes-operator/v1.3.0/getting-started/images/install/namespace-list.png b/docs/server/kubernetes-operator/v1.3.0/getting-started/images/install/namespace-list.png new file mode 100644 index 000000000..75b948c65 Binary files /dev/null and b/docs/server/kubernetes-operator/v1.3.0/getting-started/images/install/namespace-list.png differ diff --git a/docs/server/kubernetes-operator/v1.3.0/getting-started/images/install/pods-list.png b/docs/server/kubernetes-operator/v1.3.0/getting-started/images/install/pods-list.png new file mode 100644 index 000000000..5161e42a5 Binary files /dev/null and b/docs/server/kubernetes-operator/v1.3.0/getting-started/images/install/pods-list.png differ diff --git a/docs/server/kubernetes-operator/v1.3.0/getting-started/installation.md b/docs/server/kubernetes-operator/v1.3.0/getting-started/installation.md new file mode 100644 index 000000000..0e68820a9 --- /dev/null +++ b/docs/server/kubernetes-operator/v1.3.0/getting-started/installation.md @@ -0,0 +1,196 @@ +--- +title: Installation +order: 2 +--- + +This section covers the various aspects of installing the Operator. + +::: important +The Operator is an Enterprise-only feature, please [contact us](https://www.kurrent.io/contact) for more information. +::: + +## Prerequisites + +::: tip +To get the best out of this guide, a basic understanding of [Kubernetes concepts](https://kubernetes.io/docs/concepts/) is essential. +::: + +* A Kubernetes cluster running any [non-EOL version of Kubernetes](https://kubernetes.io/releases/). +* Permission to create resources, deploy the Operator and install CRDs in the target cluster. +* The following CLI tools installed, on your shell’s `$PATH`, with `$KUBECONFIG` pointing to your cluster: + * [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl) + * [k9s](https://k9scli.io/topics/install/) + * [Helm 3 CLI](https://helm.sh/docs/intro/install/) + * A valid Operator license. Please [contact us](https://www.kurrent.io/contact) for more information. + +## Configure Helm Repository + +Add the Kurrent Helm repository to your local environment: + +```bash +helm repo add kurrent-latest \ + 'https://packages.kurrent.io/basic/kurrent-latest/helm/charts/' +``` + +## Install Custom Resource Definitions (CRDs) + +The Operator uses Custom Resource Definitions (CRDs) to extend Kubernetes. You can install them automatically with Helm or manually. + +The following resource types are supported: +- [KurrentDB](resource-types.md#kurrentdb) +- [KurrentDBBackup](resource-types.md#kurrentdbbackup) + +Since CRDs are managed globally by Kubernetes, special care must be taken to install them. + +### Automatic Install + +It's recommended to install and manage the CRDs using Helm. See [Deployment Modes](#deployment-modes) for more information. + +### Manual Install + +If you prefer to install CRDs yourself: + +```bash +# Download the kurrentdb-operator Helm chart +helm pull kurrent-latest/kurrentdb-operator --version 1.3.0 --untar +# Install the CRDs +kubectl apply -f kurrentdb-operator/crds +``` +*Expected Output*: +``` +customresourcedefinition.apiextensions.k8s.io/kurrentdbbackups.kubernetes.kurrent.io created +customresourcedefinition.apiextensions.k8s.io/kurrentdbs.kubernetes.kurrent.io created +``` + +After installing CRDs manually, you should include the `--skip-crds` flag for the `helm install` and +`helm upgrade` commands. + +## Deployment Modes + +The Operator can be scoped to track Kurrent resources across **all** or **specific** namespaces. + +### Cluster-wide + +In cluster-wide mode, the Operator tracks Kurrent resources across **all** namespaces and requires `ClusterRole`. Helm creates the ClusteRole automatically. + +To deploy the Operator in this mode, run: + +```bash +helm install kurrentdb-operator kurrent-latest/kurrentdb-operator \ + --version 1.3.0 \ + --namespace kurrent \ + --create-namespace \ + --set-file operator.license.key=/path/to/license.key \ + --set-file operator.license.file=/path/to/license.lic +``` + +This command: +- Deploys the Operator into the `kurrent` namespace (use `--create-namespace` to create it). Feel free to modify this namespace. +- Creates the namespace (if it already exists, leave out the `--create-namespace` flag). +- Deploys CRDs (this can be skipped by removing `--skip-crds`). +- Applys the Operator license. +- Deploys a new Helm release called `kurrentdb-operator` in the `kurrent` namespace. + +*Expected Output*: +``` +NAME: kurrentdb-operator +LAST DEPLOYED: Thu Mar 20 14:51:42 2025 +NAMESPACE: kurrent +STATUS: deployed +REVISION: 1 +TEST SUITE: None +``` + +Once installed, navigate to the [deployment validation](#deployment-validation) section. + +### Specific Namespace(s) + +In this mode, the Operator will track Kurrent resources across **specific** namespaces. This mode reduces the level of permissions required. The Operator will create a `Role` in each namespace that it is expected to manage. + +To deploy the Operator in this mode, the following command can be used: + +```bash +helm install kurrentdb-operator kurrent-latest/kurrentdb-operator \ + --version 1.3.0 \ + --namespace kurrent \ + --create-namespace \ + --set-file operator.license.key=/path/to/license.key \ + --set-file operator.license.file=/path/to/license.lic \ + --set operator.namespaces='{kurrent, foo}' +``` + +Here's what the command does: +- Sets the namespace of where the Operator will be deployed i.e. `kurrent` (feel free to change this) +- Creates the namespace (if it already exists, leave out the `--create-namespace` flag) +- Deploys CRDs (this can be skipped by setting `--skip-crds`) +- Configures the Operator license +- Configures the Operator to operate on resources the namespaces `kurrent` and `foo` +- Deploys a new Helm release called `kurrentdb-operator` in the `kurrent` namespace + +::: important +Make sure the namespaces listed as part of the `operator.namespaces` parameter already exist before running the command. +::: + +*Expected Output*: +``` +NAME: kurrentdb-operator +LAST DEPLOYED: Thu Mar 20 14:51:42 2025 +NAMESPACE: kurrent +STATUS: deployed +REVISION: 1 +TEST SUITE: None +``` + +Once installed, navigate to the [deployment validation](#deployment-validation) section. + +#### Augmenting Namespaces + +The Operator deployment can be updated to adjust which namespaces are watched. For example, in addition to the `kurrent` and `foo` namespaces (from the example above), a new namespace `bar` may also be watched using the command below: + +```bash +helm upgrade kurrentdb-operator kurrent-latest/kurrentdb-operator \ + --version 1.3.0 \ + --namespace kurrent \ + --reuse-values \ + --set operator.namespaces='{kurrent,foo,bar}' +``` + +This will trigger: +- a new `Role` to be created in the `bar` namespace +- a rolling restart of the Operator to pick up the new configuration changes + +## Deployment Validation + +Using the k9s tool, navigate to the namespace listing using the command `:namespaces`. It should show the namespace where the Operator was deployed: + +![Namespaces](images/install/namespace-list.png) + +After stepping in to the `kurrent` namespace, type `:deployments` in the k9s console. It should show the following: + +![Operator Deployment](images/install/deployments-list.png) + +Pods may also be viewed using the `:pods` command, for example: + +![Operator Pod](images/install/pods-list.png) + +Pressing the `Return` key on the selected Operator pod will allow you to drill through the container hosted in the pod, and then finally to the logs: + +![Operator Logs](images/install/logs.png) + + +## Upgrading an Installation + +The Operator can be upgraded using the following `helm` commands: + +```bash +helm repo update +helm upgrade kurrentdb-operator kurrentdb-operator-repo/kurrentdb-operator \ + --namespace kurrent \ + --version {version} +``` + +Here's what these commands do: +- Refresh the local Helm repository index +- Locates an existing operator installation in namespace `kurrent` +- Selects the target upgrade version `{version}` e.g. `1.3.0` +- Performs the upgrade, preserving values that were set during installation diff --git a/docs/server/kubernetes-operator/v1.3.0/getting-started/resource-types.md b/docs/server/kubernetes-operator/v1.3.0/getting-started/resource-types.md new file mode 100644 index 000000000..591457d2d --- /dev/null +++ b/docs/server/kubernetes-operator/v1.3.0/getting-started/resource-types.md @@ -0,0 +1,184 @@ +--- +title: Supported Resource Types +order: 3 +--- + +The Operator supports the following resource types (known as `Kind`'s): +- `KurrentDB` +- `KurrentDBBackup` + +## KurrentDB + +This resource type is used to define a database deployment. + +### API + +| Field | Required | Description | +|---------------------------------------------------------------------------------------------------------------------------------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------| +| `replicas` _integer_ | Yes | Number of nodes in a database cluster (1 or 3) | +| `image` _string_ | Yes | KurrentDB container image URL | +| `resources` _[ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#resourcerequirements-v1-core)_ | No | Database container resource limits and requests | +| `storage` _[PersistentVolumeClaim](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#persistentvolumeclaimspec-v1-core)_ | Yes | Persistent volume claim settings for the underlying data volume | +| `network` _[KurrentDBNetwork](#kurrentdbnetwork)_ | Yes | Defines the network configuration to use with the database | +| `configuration` _yaml_ | No | Additional configuration to use with the database, see [below](#configuring-kurrent-db) | +| `sourceBackup` _string_ | No | Backup name to restore a cluster from | +| `security` _[KurrentDBSecurity](#kurrentdbsecurity)_ | No | Security configuration to use for the database. This is optional, if not specified the cluster will be created without security enabled. | +| `licenseSecret` _[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#secretkeyselector-v1-core)_ | No | A secret that contains the Enterprise license for the database | +| `constraints` _[KurrentDBConstraints](#kurrentdbconstraints)_ | No | Scheduling constraints for the Kurrent DB pod. | +| `readOnlyReplias` _[KurrentDBReadOnlyReplicasSpec](#kurrentdbreadonlyreplicasspec)_ | No | Read-only replica configuration the Kurrent DB Cluster. | +| `extraMetadata` _[KurrentDBExtraMetadataSpec](#kurrentdbextrametadataspec)_ | No | Additional annotations and labels for child resources. | + +#### KurrentDBReadOnlyReplicasSpec + +Other than `replicas`, each of the fields in `KurrentDBReadOnlyReplicasSpec` default to the corresponding values from the main KurrentDBSpec. + +| Field | Required | Description | +|---------------------------------------------------------------------------------------------------------------------------------------------|----------|------------------------------------------------------------------| +| `replicas` _integer_ | No | Number of read-only replicas in the cluster. Defaults to zero. | +| `resources` _[ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#resourcerequirements-v1-core)_ | No | Database container resource limits and requests. | +| `storage` _[PersistentVolumeClaim](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#persistentvolumeclaimspec-v1-core)_ | No | Persistent volume claim settings for the underlying data volume. | +| `configuration` _yaml_ | No | Additional configuration to use with the database. | +| `constraints` _[KurrentDBConstraints](#kurrentdbconstraints)_ | No | Scheduling constraints for the Kurrent DB pod. | + +#### KurrentDBConstraints + +| Field | Required | Description | +|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|-------------------------------------------------------------------------------------------| +| `nodeSelector` _yaml_ | No | Identifies nodes that the Kurrent DB may consider during scheduling. | +| `affinity` _[Affinity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#affinity-v1-core)_ | No | The node affinity, pod affinity, and pod anti-affinity for scheduling the Kurrent DB pod. | +| `tolerations` _list of [Toleration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#toleration-v1-core)_ | No | The tolerations for scheduling the Kurrent DB pod. | +| `topologySpreadConstraints` _list of [TopologySpreadConstraint](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#topologyspreadconstraint-v1-core)_ | No | The topology spread constraints for scheduling the Kurrent DB pod. | + +#### KurrentDBExtraMetadataSpec + +| Field | Required | Description | +|------------------------------------------------------------------|----------|---------------------------------------------------------------------| +| All _[ExtraMetadataSpec](#extrametadataspec)_ | No | Extra annotations and labels for all child resource types. | +| ConfigMaps _[ExtraMetadataSpec](#extrametadataspec)_ | No | Extra annotations and labels for ConfigMaps. | +| StatefulSets _[ExtraMetadataSpec](#extrametadataspec)_ | No | Extra annotations and labels for StatefulSets. | +| Pods _[ExtraMetadataSpec](#extrametadataspec)_ | No | Extra annotations and labels for Pods. | +| PersistentVolumeClaims _[ExtraMetadataSpec](#extrametadataspec)_ | No | Extra annotations and labels for PersistentVolumeClaims. | +| HeadlessServices _[ExtraMetadataSpec](#extrametadataspec)_ | No | Extra annotations and labels for the per-cluster headless Services. | +| HeadlessPodServices _[ExtraMetadataSpec](#extrametadataspec)_ | No | Extra annotations and labels for the per-pod headless Services. | +| LoadBalancers _[ExtraMetadataSpec](#extrametadataspec)_ | No | Extra annotations and labels for LoadBalancer-type Services. | + +#### ExtraMetadataSpec + +| Field | Required | Description +|-----------------------|-----------|-----------------------------------| +| Labels _object_ | No | Extra labels for a resource. | +| Annotations _object_ | No | Extra annotations for a resource. | + +#### KurrentDBNetwork + +| Field | Required | Description | +|------------------------------------------------------------------|----------|----------------------------------------------------------------------------------| +| `domain` _string_ | Yes | Domain used for external DNS e.g. advertised address exposed in the gossip state | +| `loadBalancer` _[KurrentDBLoadBalancer](#kurrentdbloadbalancer)_ | Yes | Defines a load balancer to use with the database | +| `fqdnTemplate` _string_ | No | The template string used to define the external advertised address of a node | + +Note that `fqdnTemplate` supports the following expansions: +- `{name}` expands to KurrentDB.metadata.name +- `{namespace}` expands to KurretnDB.metadata.namespace +- `{domain}` expands to the KurrnetDBNetwork.domain +- `{podName}` expands to the name of the pod +- `{nodeTypeSuffix}` expands to `""` for a primary node or `"-replica"` for a replica node + +When `fqdnTemplate` is empty, it defaults to `{podName}.{name}{nodeTypeSuffix}.{domain}`. + +#### KurrentDBLoadBalancer + +| Field | Required | Description | +|------------------------------|----------|--------------------------------------------------------------------------------| +| `enabled` _boolean_ | Yes | Determines if a load balancer should be deployed for each node | +| `allowedIps` _string array_ | No | List of IP ranges allowed by the load balancer (default will allow all access) | + +#### KurrentDBSecurity + +| Field | Required | Description | +|------------------------------------------------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------| +| `certificateReservedNodeCommonName` _string_ | No | Common name for the TLS certificate (this maps directly to the database property `CertificateReservedNodeCommonName`) | +| `certificateAuthoritySecret` _[CertificateSecret](#certificatesecret)_ | No | Secret containing the CA TLS certificate. | +| `certificateSecret` _[CertificateSecret](#certificatesecret)_ | Yes | Secret containing the TLS certificate to use. | +| `certificateSubjectName` _string_ | No | Deprecated field. The value of this field is always ignored. | + +#### CertificateSecret + +| Field | Required | Description | +|---------------------------|----------|------------------------------------------------------------------| +| `name` _string_ | Yes | Name of the secret holding the certificate details | +| `keyName` _string_ | Yes | Key within the secret containing the TLS certificate | +| `privateKeyName` _string_ | No | Key within the secret containing the TLS certificate private key | + + +## KurrentDBBackup + +This resource type is used to define a backup for an existing database deployment. + +:::important +Resources of this type must be created within the same namespace as the target database cluster to backup. +::: + +### API + +| Field | Required | Description | +|-----------------------------------------------------------------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------| +| `clusterName` _string_ | Yes | Name of the source database cluster | +| `nodeName` _string_ | No | Specific node name within the database cluster to use as the backup. If this is not specified, the leader will be picked as the source. | +| `volumeSnapshotClassName` _string_ | Yes | The name of the underlying volume snapshot class to use. | +| `extraMetadata` _[KurrentDBBackupExtraMetadataSpec](#kurrentdbbackupextrametadataspec)_ | No | Additional annotations and labels for child resources. | + +#### KurrentDBBackupExtraMetadataSpec + +| Field | Required | Description | +|------------------------------------------------------------------|----------|---------------------------------------------------------------------------------------------| +| All _[ExtraMetadataSpec](#extrametadataspec)_ | No | Extra annotations and labels for all child resource types (currently only VolumeSnapshots). | +| VolumeSnapshots _[ExtraMetadataSpec](#extrametadataspec)_ | No | Extra annotations and labels for VolumeSnapshots. | + +## Configuring Kurrent DB + +The [`KurrentDB.spec.configuration` yaml field](#kurrentdb) may contain any valid configuration values for Kurrent +DB. However, some values may be unnecessary, as the Operator provides some defaults, while other +values may be ignored, as the Operator may override them. + +The Operator-defined default configuration values, which may be overridden by the user's +`KurrentDB.spec.configuration` are: + +| Default Field | Default Value | +|------------------------------|---------------| +| DisableLogFile | true | +| EnableAtomPubOverHTTP | true | +| Insecure | false | +| PrepareTimeoutMs | 3000 | +| CommitTimeoutMs | 3000 | +| GossipIntervalMs | 2000 | +| GossipTimeoutMs | 5000 | +| LeaderElectionTimeoutMs | 2000 | +| ReplicationHeartbeatInterval | 1000 | +| ReplicationHeartbeatTimeout | 2500 | +| NodeHeartbeatInterval | 1000 | +| NodeHeartbeatTimeout | 2500 | + +The Operator-managed configuration values, which take precedence over the user's +`KurrentDB.spec.configuration`, are: + + + + +| Managed Field | Value | +|------------------------------| -------------------------------------------------------------| +| Db | hard-coded volume mount point | +| Index | hard-coded volume mount point | +| Log | hard-coded volume mount point | +| Insecure | true if `KurrentDB.spec.security.certificateSecret` is empty | +| DiscoverViaDns | false (`GossipSeed` is used instead) | +| AllowAnonymousEndpointAccess | true | +| AllowUnknownOptions | true | +| NodeIp | 0.0.0.0 (to accept traffic from outside pod) | +| ReplicationIp | 0.0.0.0 (to accept traffic from outside pod) | +| NodeHostAdvertiseAs | Derived from pod name | +| ReplicationHostAdvertiseAs | Derived from pod name | +| AdveritseHostToClientAs | Derived from `KurrentDB.spec.newtork.fqdnTemplate` | +| ClusterSize | Derived from `KurrentDB.spec.replicas` | +| GossipSeed | Derived from pod list | +| ReadOnlyReplica | Automatically set for ReadOnlyReplica pods | diff --git a/docs/server/kubernetes-operator/v1.3.0/operations/README.md b/docs/server/kubernetes-operator/v1.3.0/operations/README.md new file mode 100644 index 000000000..90833bd40 --- /dev/null +++ b/docs/server/kubernetes-operator/v1.3.0/operations/README.md @@ -0,0 +1,11 @@ +--- +order: 2 +dir: + text: "Operations" + link: true + order: 1 +--- + +A number of operations can be performed with the Operator which are catalogued below: + + \ No newline at end of file diff --git a/docs/server/kubernetes-operator/v1.3.0/operations/database-backup.md b/docs/server/kubernetes-operator/v1.3.0/operations/database-backup.md new file mode 100644 index 000000000..ee29968fb --- /dev/null +++ b/docs/server/kubernetes-operator/v1.3.0/operations/database-backup.md @@ -0,0 +1,77 @@ +--- +title: Database Backup +order: 3 +--- + +The sections below detail how database backups can be performed. Refer to the [KurrentDBBackup API](../getting-started/resource-types.md#kurrentdbbackup) for detailed information. + +## Backing up the leader + +Assuming there is a cluster called `kurrentdb-cluster` that resides in the `kurrent` namespace, the following `KurrentDBBackup` resource can be defined: + +```yaml +apiVersion: kubernetes.kurrent.io/v1 +kind: KurrentDBBackup +metadata: + name: kurrentdb-cluster +spec: + volumeSnapshotClassName: ebs-vs + clusterName: kurrentdb-cluster +``` + +In the example above, the backup definition leverages the `ebs-vs` volume snapshot class to perform the underlying volume snapshot. This class name will vary per Kubernetes cluster/Cloud provider, please consult with your Kubernetes administrator to determine this value. + +The `KurrentDBBackup` type takes an optional `nodeName`. If left blank, the leader will be derived based on the gossip state of the database cluster. + +The example above can be deployed using the following steps: +- Copy the YAML snippet above to a file called `backup.yaml` +- Run the following command: + +```bash +kubectl -n kurrent apply -f backup.yaml +``` + +Once deployed, navigate to the [Viewing Backups](#viewing-backups) section. + +## Backing up a specific node + +Assuming there is a cluster called `kurrentdb-cluster` that resides in the `kurrent` namespace, the following `KurrentDBBackup` resource can be defined: + +```yaml +apiVersion: kubernetes.kurrent.io/v1 +kind: KurrentDBBackup +metadata: + name: kurrentdb-cluster +spec: + volumeSnapshotClassName: ebs-vs + clusterName: kurrentdb-cluster + nodeName: kurrentdb-1 +``` + +In the example above, the backup definition leverages the `ebs-vs` volume snapshot class to perform the underlying volume snapshot. This class name will vary per Kubernetes cluster, please consult with your Kubernetes administrator to determine this value. + +The example above can be deployed using the following steps: +- Copy the YAML snippet above to a file called `backup.yaml` +- Run the following command: + +```bash +kubectl -n kurrent apply -f backup.yaml +``` + +Once deployed, navigate to the [Viewing Backups](#viewing-backups) section. + +## Viewing Backups + +Using the k9s tool, navigate to the namespaces list using the command `:namespaces`, it should show a screen similar to: + +![Namespaces](images/database-backup/namespace-list.png) + +From here, press the `Return` key on the namespace where the `KurrentDBBackup` was created, in the screen above the namespace is `kurrent`. Now enter the k9s command `:kurrentdbbackups` and press the `Return` key. The following screen will show a list of database backups for the selected namespace. + +![Backup Listing](images/database-backup/backup-list.png) + +## Periodic Backups + +You can use [Kubernetes ChronJobs]( +https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/) for basic periodic backup +functionality. diff --git a/docs/server/kubernetes-operator/v1.3.0/operations/database-deployment.md b/docs/server/kubernetes-operator/v1.3.0/operations/database-deployment.md new file mode 100644 index 000000000..5f21a2371 --- /dev/null +++ b/docs/server/kubernetes-operator/v1.3.0/operations/database-deployment.md @@ -0,0 +1,654 @@ +--- +title: Database Deployment +order: 1 +--- + +The sections below detail the different deployment options for KurrentDB. For detailed information on the various properties, visit the [KurrentDB API](../getting-started/resource-types.md#kurrentdb) section. + +## Prerequisites + +Before deploying a `KurrentDB` cluster, the following requirements should be met: + +* The Operator has been installed as per the [Installation](../getting-started/installation.md) section. +* The following CLI tools are installed and configured to interact with your Kubernetes cluster. This means the tool must be accessible from your shell's `$PATH`, and your `$KUBECONFIG` environment variable must point to the correct Kubernetes configuration file: + * [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl) + * [k9s](https://k9scli.io/topics/install/) + +:::important +With the examples listed in this guide, the Operator is assumed to have been deployed such that it can track the `kurrent` namespace for deployments. +::: + +## Single Node Insecure Cluster + +The following `KurrentDB` resource type defines a single node cluster with the following properties: +- The database will be deployed in the `kurrent` namespace with the name `kurrentdb-cluster` +- Security is not enabled +- KurrentDB version 25.0.0 will be used +- 1vcpu will be requested as the minimum (upper bound is unlimited) +- 1gb of memory will be used +- 512mb of storage will be allocated for the data disk +- The KurrentDB instance that is provisioned will be exposed as `kurrentdb-0.kurrentdb-cluster.kurrent.test` + +```yaml +apiVersion: kubernetes.kurrent.io/v1 +kind: KurrentDB +metadata: + name: kurrentdb-cluster + namespace: kurrent +spec: + replicas: 1 + image: docker.kurrent.io/kurrent-latest/kurrentdb:25.0.0 + resources: + requests: + cpu: 1000m + memory: 1Gi + storage: + volumeMode: "Filesystem" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 512Mi + network: + domain: kurrentdb-cluster.kurrent.test + loadBalancer: + enabled: true +``` + +This can be deployed using the following steps: +- Copy the YAML snippet above to a file called `cluster.yaml` +- Ensure that the `kurrent` namespace has been created +- Run the following command: + +```bash +kubectl apply -f cluster.yaml +``` + +Once deployed, navigate to the [Viewing Deployments](#viewing-deployments) section. + +## Three Node Insecure Cluster + +The following `KurrentDB` resource type defines a three node cluster with the following properties: +- The database will be deployed in the `kurrent` namespace with the name `kurrentdb-cluster` +- Security is not enabled +- KurrentDB version 25.0.0 will be used +- 1vcpu will be requested as the minimum (upper bound is unlimited) per node +- 1gb of memory will be used per node +- 512mb of storage will be allocated for the data disk per node +- The KurrentDB instances that are provisioned will be exposed as `kurrentdb-{idx}.kurrentdb-cluster.kurrent.test` + +```yaml +apiVersion: kubernetes.kurrent.io/v1 +kind: KurrentDB +metadata: + name: kurrentdb-cluster + namespace: kurrent +spec: + replicas: 3 + image: docker.kurrent.io/kurrent-latest/kurrentdb:25.0.0 + resources: + requests: + cpu: 1000m + memory: 1Gi + storage: + volumeMode: "Filesystem" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 512Mi + network: + domain: kurrentdb-cluster.kurrent.test + loadBalancer: + enabled: true +``` + +This can be deployed using the following steps: +- Copy the YAML snippet above to a file called `cluster.yaml` +- Ensure that the `kurrent` namespace has been created +- Run the following command: + +```bash +kubectl apply -f cluster.yaml +``` + +Once deployed, navigate to the [Viewing Deployments](#viewing-deployments) section. + +## Three Node Insecure Cluster with Two Read-Only Replicas + +Note that read-only replicas are only supported by KurrentDB in clustered configurations, that is, +with multiple primary nodes. + +The following `KurrentDB` resource type defines a three node cluster with the following properties: +- The database will be deployed in the `kurrent` namespace with the name `kurrentdb-cluster` +- Security is not enabled +- KurrentDB version 25.0.0 will be used +- 1vcpu will be requested as the minimum (upper bound is unlimited) per node +- 1gb of memory will be used per primary node, but read-only replicas will have 2gb of memory +- 512mb of storage will be allocated for the data disk per node +- The main KurrentDB instances that are provisioned will be exposed as `kurrentdb-{idx}.kurrentdb-cluster.kurrent.test` +- The read-only replicas that are provisioned will be exposed as `kurrentdb-replica-{idx}.kurrentdb-cluster.kurrent.test` + +```yaml +apiVersion: kubernetes.kurrent.io/v1 +kind: KurrentDB +metadata: + name: kurrentdb-cluster + namespace: kurrent +spec: + replicas: 3 + image: docker.kurrent.io/kurrent-latest/kurrentdb:25.0.0 + resources: + requests: + cpu: 1000m + memory: 1Gi + storage: + volumeMode: "Filesystem" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 512Mi + network: + domain: kurrentdb-cluster.kurrent.test + loadBalancer: + enabled: true + readOnlyReplicas: + replicas: 2 + resources: + requests: + cpu: 1000m + memory: 1Gi + +``` + +This can be deployed using the following steps: +- Copy the YAML snippet above to a file called `cluster.yaml` +- Ensure that the `kurrent` namespace has been created +- Run the following command: + +```bash +kubectl apply -f cluster.yaml +``` + +Once deployed, navigate to the [Viewing Deployments](#viewing-deployments) section. + +## Single Node Secure Cluster (using self-signed certificates) + +The following `KurrentDB` resource type defines a single node cluster with the following properties: +- The database will be deployed in the `kurrent` namespace with the name `kurrentdb-cluster` +- Security is enabled using self-signed certificates +- KurrentDB version 25.0.0 will be used +- 1vcpu will be requested as the minimum (upper bound is unlimited) +- 1gb of memory will be used +- 512mb of storage will be allocated for the data disk +- The KurrentDB instance that is provisioned will be exposed as `kurrentdb-cluster-0.kurrentdb-cluster.kurrent.test` + +```yaml +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: kurrentdb-cluster + namespace: kurrent +spec: + secretName: kurrentdb-cluster-tls + isCA: false + usages: + - client auth + - server auth + - digital signature + - key encipherment + commonName: kurrentdb-node + subject: + organizations: + - Kurrent + organizationalUnits: + - Cloud + dnsNames: + - '*.kurrentdb-cluster.kurrent.svc.cluster.local' + - '*.kurrentdb-cluster.kurrent.test' + - '*.kurrentdb-cluster-replica.kurrent.svc.cluster.local' + - '*.kurrentdb-cluster-replica.kurrent.test' + privateKey: + algorithm: RSA + encoding: PKCS1 + size: 2048 + issuerRef: + name: ca-issuer + kind: Issuer +--- +apiVersion: kubernetes.kurrent.io/v1 +kind: KurrentDB +metadata: + name: kurrentdb-cluster + namespace: kurrent +spec: + replicas: 1 + image: docker.kurrent.io/kurrent-latest/kurrentdb:25.0.0 + resources: + requests: + cpu: 1000m + memory: 1Gi + storage: + volumeMode: "Filesystem" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 512Mi + network: + domain: kurrentdb-cluster.kurrent.test + loadBalancer: + enabled: true + security: + certificateAuthoritySecret: + name: ca-tls + keyName: ca.crt + certificateSecret: + name: kurrentdb-cluster-tls + keyName: tls.crt + privateKeyName: tls.key +``` + +Before deploying this cluster, ensure that the steps described in section [Using Self-Signed certificates](managing-certificates.md#using-self-signed-certificates) have been followed. + +Follow these steps to deploy the cluster: +- Copy the YAML snippet above to a file called `cluster.yaml` +- Ensure that the `kurrent` namespace has been created +- Run the following command: + +```bash +kubectl apply -f cluster.yaml +``` + +Once deployed, navigate to the [Viewing Deployments](#viewing-deployments) section. + +## Three Node Secure Cluster (using self-signed certificates) + +The following `KurrentDB` resource type defines a three node cluster with the following properties: +- The database will be deployed in the `kurrent` namespace with the name `kurrentdb-cluster` +- Security is enabled using self-signed certificates +- KurrentDB version 25.0.0 will be used +- 1vcpu will be requested as the minimum (upper bound is unlimited) per node +- 1gb of memory will be used per node +- 512mb of storage will be allocated for the data disk per node +- The KurrentDB instance that is provisioned will be exposed as `kurrentdb-{idx}.kurrentdb-cluster.kurrent.test` + +```yaml +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: kurrentdb-cluster + namespace: kurrent +spec: + secretName: kurrentdb-cluster-tls + isCA: false + usages: + - client auth + - server auth + - digital signature + - key encipherment + commonName: kurrentdb-node + subject: + organizations: + - Kurrent + organizationalUnits: + - Cloud + dnsNames: + - '*.kurrentdb-cluster.kurrent.svc.cluster.local' + - '*.kurrentdb-cluster.kurrent.test' + - '*.kurrentdb-cluster-replica.kurrent.svc.cluster.local' + - '*.kurrentdb-cluster-replica.kurrent.test' + privateKey: + algorithm: RSA + encoding: PKCS1 + size: 2048 + issuerRef: + name: ca-issuer + kind: Issuer +--- +apiVersion: kubernetes.kurrent.io/v1 +kind: KurrentDB +metadata: + name: kurrentdb-cluster + namespace: kurrent +spec: + replicas: 3 + image: docker.kurrent.io/kurrent-latest/kurrentdb:25.0.0 + resources: + requests: + cpu: 1000m + memory: 1Gi + storage: + volumeMode: "Filesystem" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 512Mi + network: + domain: kurrentdb-cluster.kurrent.test + loadBalancer: + enabled: true + security: + certificateAuthoritySecret: + name: ca-tls + keyName: ca.crt + certificateSecret: + name: kurrentdb-cluster-tls + keyName: tls.crt + privateKeyName: tls.key +``` + +Before deploying this cluster, ensure that the steps described in section [Using Self-Signed certificates](managing-certificates.md#using-self-signed-certificates) have been followed. + +Follow these steps to deploy the cluster: +- Copy the YAML snippet above to a file called `cluster.yaml` +- Ensure that the `kurrent` namespace has been created +- Run the following command: + +```bash +kubectl apply -f cluster.yaml +``` + +Once deployed, navigate to the [Viewing Deployments](#viewing-deployments) section. + +## Single Node Secure Cluster (using LetsEncrypt) + +The following `KurrentDB` resource type defines a single node cluster with the following properties: +- The database will be deployed in the `kurrent` namespace with the name `kurrentdb-cluster` +- Security is enabled using certificates from LetsEncrypt +- KurrentDB version 25.0.0 will be used +- 1vcpu will be requested as the minimum (upper bound is unlimited) +- 1gb of memory will be used +- 512mb of storage will be allocated for the data disk +- The KurrentDB instance that is provisioned will be exposed as `kurrentdb-cluster-0.kurrentdb-cluster.kurrent.test` + +```yaml +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: kurrentdb-cluster + namespace: kurrent +spec: + secretName: kurrentdb-cluster-tls + isCA: false + usages: + - client auth + - server auth + - digital signature + - key encipherment + commonName: kurrentdb-node + subject: + organizations: + - Kurrent + organizationalUnits: + - Cloud + dnsNames: + - '*.kurrentdb-cluster.kurrent.svc.cluster.local' + - '*.kurrentdb-cluster.kurrent.test' + - '*.kurrentdb-cluster-replica.kurrent.svc.cluster.local' + - '*.kurrentdb-cluster-replica.kurrent.test' + privateKey: + algorithm: RSA + encoding: PKCS1 + size: 2048 + issuerRef: + name: letsencrypt + kind: Issuer +--- +apiVersion: kubernetes.kurrent.io/v1 +kind: KurrentDB +metadata: + name: kurrentdb-cluster + namespace: kurrent +spec: + replicas: 1 + image: docker.kurrent.io/kurrent-latest/kurrentdb:25.0.0 + resources: + requests: + cpu: 1000m + memory: 1Gi + storage: + volumeMode: "Filesystem" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 512Mi + network: + domain: kurrentdb-cluster.kurrent.test + loadBalancer: + enabled: true + security: + certificateSecret: + name: kurrentdb-cluster-tls + keyName: tls.crt + privateKeyName: tls.key +``` + +Before deploying this cluster, ensure that the steps described in section [Using LetsEncrypt certificates](managing-certificates.md#using-trusted-certificates-via-letsencrypt) have been followed. + +Follow these steps to deploy the cluster: +- Copy the YAML snippet above to a file called `cluster.yaml` +- Ensure that the `kurrent` namespace has been created +- Run the following command: + +```bash +kubectl apply -f cluster.yaml +``` + +## Three Node Secure Cluster (using LetsEncrypt) + +The following `KurrentDB` resource type defines a three node cluster with the following properties: +- The database will be deployed in the `kurrent` namespace with the name `kurrentdb-cluster` +- Security is enabled using certificates from LetsEncrypt +- KurrentDB version 25.0.0 will be used +- 1vcpu will be requested as the minimum (upper bound is unlimited) per node +- 1gb of memory will be used per node +- 512mb of storage will be allocated for the data disk per node +- The KurrentDB instance that is provisioned will be exposed as `kurrentdb-{idx}.kurrentdb-cluster.kurrent.test` + +```yaml +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: kurrentdb-cluster + namespace: kurrent +spec: + secretName: kurrentdb-cluster-tls + isCA: false + usages: + - client auth + - server auth + - digital signature + - key encipherment + commonName: kurrentdb-node + subject: + organizations: + - Kurrent + organizationalUnits: + - Cloud + dnsNames: + - '*.kurrentdb-cluster.kurrent.svc.cluster.local' + - '*.kurrentdb-cluster.kurrent.test' + - '*.kurrentdb-cluster-replica.kurrent.svc.cluster.local' + - '*.kurrentdb-cluster-replica.kurrent.test' + privateKey: + algorithm: RSA + encoding: PKCS1 + size: 2048 + issuerRef: + name: letsencrypt + kind: Issuer +--- +apiVersion: kubernetes.kurrent.io/v1 +kind: KurrentDB +metadata: + name: kurrentdb-cluster + namespace: kurrent +spec: + replicas: 3 + image: docker.kurrent.io/kurrent-latest/kurrentdb:25.0.0 + resources: + requests: + cpu: 1000m + memory: 1Gi + storage: + volumeMode: "Filesystem" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 512Mi + network: + domain: kurrentdb-cluster.kurrent.test + loadBalancer: + enabled: true + security: + certificateSecret: + name: kurrentdb-cluster-tls + keyName: tls.crt + privateKeyName: tls.key +``` + +Before deploying this cluster, ensure that the steps described in section [Using LetsEncrypt certificates](managing-certificates.md#using-trusted-certificates-via-letsencrypt) have been followed. + +Follow these steps to deploy the cluster: +- Copy the YAML snippet above to a file called `cluster.yaml` +- Ensure that the `kurrent` namespace has been created +- Run the following command: + +```bash +kubectl apply -f cluster.yaml +``` + +Once deployed, navigate to the [Viewing Deployments](#viewing-deployments) section. + + +## Deploying With Scheduling Constraints + +The pods created for a KurrentDB resource can be configured with any of the constraints commonly applied to pods: + +- [Node Selectors](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector) +- [Affinity and Anti-Affinity](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity) +- [Topology Spread Constraints](https://kubernetes.io/docs/concepts/scheduling-eviction/topology-spread-constraints/) +- [Tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) +- [Node Name](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodename) + +For example, in cloud deployments, you may want to maximize uptime by asking each replica of a +KurrentDB cluster to be deployed in a different availability zone. The following KurrentDB resource +does that, and also requires KurrentDB to schedule pods onto nodes labeled with +`machine-size:large`: + +```yaml +apiVersion: kubernetes.kurrent.io/v1 +kind: KurrentDB +metadata: + name: my-kurrentdb-cluster + namespace: kurrent +spec: + replicas: 3 + image: docker.kurrent.io/kurrent-latest/kurrentdb:25.0.0 + resources: + requests: + cpu: 1000m + memory: 1Gi + storage: + volumeMode: "Filesystem" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 512Mi + network: + domain: kurrentdb-cluster.kurrent.test + loadBalancer: + enabled: true + constraints: + nodeSelector: + machine-size: large + topologySpreadConstraints: + maxSkew: 1 + topologyKey: zone + labelSelector: + matchLabels: + app.kubernetes.io/part-of: kurrentdb-operator + app.kubernetes.io/name: my-kurrentdb-cluster + whenUnsatisfiable: DoNotSchedule + +``` + +If no scheduling constraints are configured, the operator sets a default soft constraint configuring +pod anti-affinity such that multiple replicas will prefer to run on different nodes, for better +fault tolerance. + +## Viewing Deployments + +Using the k9s tool, navigate to the namespaces list using the command `:namespaces`, it should show a screen similar to: + +![Namespaces](images/database-deployment/namespace-list.png) + +From here, press the `Return` key on the namespace where `KurrentDB` was deployed. In the screen above the namespace is `kurrent`. Now enter the k9s command `:kurrentdbs` and press the `Return` key. The following screen will show a list of deployed databases for the selected namespace, as shown below: + +![Databases](images/database-deployment/database-list.png) + +Summary information is shown on this screen. For more information press the `d` key on the selected database. The following screen will provide additional information about the deployment: + +![Database Details](images/database-deployment/db-decribe.png) + +Scrolling further will also show the events related to the deployment, such as: + +- transitions between states +- gossip endpoint +- leader details +- database version + +## Accessing Deployments + +### External + +The Operator will create services of type `LoadBalancer` to access a KurrentDB cluster (for each node) when the `spec.network.loadBalancer.enabled` flag is set to `true`. + +Each service is annotated with `external-dns.alpha.kubernetes.io/hostname: {external cluster endpoint}` to allow the third-party tool [ExternalDNS](https://github.com/kubernetes-sigs/external-dns) to configure external access. + +### Internal + +The Operator will create headless services to access a KurrentDB cluster internally. This includes: +- One for the underlying statefulset (selects all pods) +- One per pod in the statefulset to support `Ingress` rules that require one target endpoint + +## Custom Database Configuration + +If custom parameters are required in the underlying database configuration then these can be specified using the `configuration` YAML block within a `KurrentDB`. Note, these values will be passed through as-is. + +For example, to enable projections, the deployment configuration looks as follows: + +```yaml +apiVersion: kubernetes.kurrent.io/v1 +kind: KurrentDB +metadata: + name: kurrentdb-cluster + namespace: kurrent +spec: + replicas: 1 + image: docker.kurrent.io/kurrent-latest/kurrentdb:25.0.0 + configuration: + RunProjections: all + StartStandardProjections: true + resources: + requests: + cpu: 1000m + memory: 1Gi + storage: + volumeMode: "Filesystem" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 512Mi + network: + domain: kurrentdb-cluster.kurrent.test + loadBalancer: + enabled: true +``` diff --git a/docs/server/kubernetes-operator/v1.3.0/operations/database-restore.md b/docs/server/kubernetes-operator/v1.3.0/operations/database-restore.md new file mode 100644 index 000000000..50c8aaf58 --- /dev/null +++ b/docs/server/kubernetes-operator/v1.3.0/operations/database-restore.md @@ -0,0 +1,33 @@ +--- +title: Database Restore +order: 4 +--- + +The sections below detail how a database restore can be performed. Refer to the [KurrentDB API](../getting-started/resource-types.md#kurrentdb) for detailed information. + +## Restoring from a backup + +A `KurrentDB` cluster can be restored from a backup by specifying an additional field `sourceBackup` as part of the cluster definition. + +For example, if an existing `KurrentDBBackup` exists called `kurrentdb-cluster-backup`, the following snippet could be used to restore it: + + +```yaml +apiVersion: kubernetes.kurrent.io/v1 +kind: KurrentDB +metadata: + name: kurrentdb-cluster + namespace: kurrent +spec: + replicas: 1 + image: docker.kurrent.io/kurrent-latest/kurrentdb:25.0.0 + sourceBackup: kurrentdb-cluster-backup + resources: + requests: + cpu: 1000m + memory: 1Gi + network: + domain: kurrentdb-cluster.kurrent.test + loadBalancer: + enabled: true +``` diff --git a/docs/server/kubernetes-operator/v1.3.0/operations/images/certs/ca-issuer-details.png b/docs/server/kubernetes-operator/v1.3.0/operations/images/certs/ca-issuer-details.png new file mode 100644 index 000000000..430f66453 Binary files /dev/null and b/docs/server/kubernetes-operator/v1.3.0/operations/images/certs/ca-issuer-details.png differ diff --git a/docs/server/kubernetes-operator/v1.3.0/operations/images/certs/ca-issuer.png b/docs/server/kubernetes-operator/v1.3.0/operations/images/certs/ca-issuer.png new file mode 100644 index 000000000..3a17ef3fa Binary files /dev/null and b/docs/server/kubernetes-operator/v1.3.0/operations/images/certs/ca-issuer.png differ diff --git a/docs/server/kubernetes-operator/v1.3.0/operations/images/database-backup/backup-list.png b/docs/server/kubernetes-operator/v1.3.0/operations/images/database-backup/backup-list.png new file mode 100644 index 000000000..1d7e706f5 Binary files /dev/null and b/docs/server/kubernetes-operator/v1.3.0/operations/images/database-backup/backup-list.png differ diff --git a/docs/server/kubernetes-operator/v1.3.0/operations/images/database-backup/namespace-list.png b/docs/server/kubernetes-operator/v1.3.0/operations/images/database-backup/namespace-list.png new file mode 100644 index 000000000..75b948c65 Binary files /dev/null and b/docs/server/kubernetes-operator/v1.3.0/operations/images/database-backup/namespace-list.png differ diff --git a/docs/server/kubernetes-operator/v1.3.0/operations/images/database-deployment/database-list.png b/docs/server/kubernetes-operator/v1.3.0/operations/images/database-deployment/database-list.png new file mode 100644 index 000000000..6b6ba34a9 Binary files /dev/null and b/docs/server/kubernetes-operator/v1.3.0/operations/images/database-deployment/database-list.png differ diff --git a/docs/server/kubernetes-operator/v1.3.0/operations/images/database-deployment/db-decribe.png b/docs/server/kubernetes-operator/v1.3.0/operations/images/database-deployment/db-decribe.png new file mode 100644 index 000000000..f57b3dfbd Binary files /dev/null and b/docs/server/kubernetes-operator/v1.3.0/operations/images/database-deployment/db-decribe.png differ diff --git a/docs/server/kubernetes-operator/v1.3.0/operations/images/database-deployment/namespace-list.png b/docs/server/kubernetes-operator/v1.3.0/operations/images/database-deployment/namespace-list.png new file mode 100644 index 000000000..75b948c65 Binary files /dev/null and b/docs/server/kubernetes-operator/v1.3.0/operations/images/database-deployment/namespace-list.png differ diff --git a/docs/server/kubernetes-operator/v1.3.0/operations/managing-certificates.md b/docs/server/kubernetes-operator/v1.3.0/operations/managing-certificates.md new file mode 100644 index 000000000..3c8dda20d --- /dev/null +++ b/docs/server/kubernetes-operator/v1.3.0/operations/managing-certificates.md @@ -0,0 +1,182 @@ +--- +title: Managing Certificates +order: 5 +--- + +The Operator expects consumers to leverage a thirdparty tool to generate TLS certificates that can be wired in to [KurrentDB](../getting-started/resource-types.md#kurrentdb) deployments using secrets. The sections below describe how certificates can be generated using popular vendors. + +## Picking certificate names + +Each node in each KurrentDB cluster you create will advertise a fully-qualified domain name (FQDN). +Clients will expect those advertised names to match the names you configure on your TLS +certificates. You will need to understand how the FQDN is calculated for each node in order to +request a TLS certificate that is valid for each node of your kurrentdb cluster. + +By default, the [network.fqdnTemplate field of your KurrentDB spec]( +../getting-started/resource-types.md#kurrentdbnetwork) is +`{podName}.{name}{nodeTypeSuffix}.{domain}`, which may require multiple wildcard names on your +certificate, like both `*.myName.myDomain.com` and `*.myName-replica.myDomain.com`. You may prefer +to instead configure an `fqdnTemplate` like `{podName}.{domain}`, which could be covered +by a single wildcard: `*.myDomain.com`. + +## Certificate Manager (cert-manager) + +### Prerequisites + +Before following the instructions in this section, these requirements should be met: + +* [cert-manager](https://cert-manager.io) is installed +* You have the required permissions to create/manage new resources on the Kubernetes cluster +* The following CLI tools are installed and configured to interact with your Kubernetes cluster. This means the tool must be accessible from your shell's `$PATH`, and your `$KUBECONFIG` environment variable must point to the correct Kubernetes configuration file: + * [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl) + * [k9s](https://k9scli.io/topics/install/) + +### Using trusted certificates via LetsEncrypt + +To use self-signed certficates with KurrentDB, follow these steps: + +1. Create a [LetsEncrypt Issuer](#letsencrypt-issuer) +2. Future certificates should be created using the `letsencrypt` issuer + +### LetsEncrypt Issuer + +The following example shows how a LetsEncrypt issuer can be deployed that leverages [AWS Route53](https://cert-manager.io/docs/configuration/acme/dns01/route53/): + +```yaml +apiVersion: cert-manager.io/v1 +kind: ClusterIssuer +metadata: + name: letsencrypt +spec: + acme: + privateKeySecretRef: + name: letsencrypt-issuer-key + email: { email } + preferredChain: "" + server: https://acme-v02.api.letsencrypt.org/directory + solvers: + - dns01: + route53: + region: { region } + hostedZoneID: { hostedZoneId } + accessKeyID: { accessKeyId } + secretAccessKeySecretRef: + name: aws-route53-credentials + key: secretAccessKey + selector: + dnsZones: + - { domain } + - "*.{ domain }" +``` + +This can be deployed using the following steps: +- Replace the variables `{...}` with the appropriate values +- Copy the YAML snippet above to a file called `issuer.yaml` +- Run the following command: + +```bash +kubectl -n kurrent apply -f issuer.yaml +``` + +### Using Self-Signed certificates + +To use self-signed certficates with KurrentDB, follow these steps: + +1. Create a [Self-Signed Issuer](#self-signed-issuer) +2. Create a [Self-Signed Certificate Authority](#self-signed-certificate-authority) +3. Create a [Self-Signed Certificate Authority Issuer](#self-signed-certificate-authority-issuer) +4. Future certificates should be created using the `ca-issuer` issuer + +### Self-Signed Issuer + +The following example shows how a self-signed issuer can be deployed: + +```yaml +apiVersion: cert-manager.io/v1 +kind: ClusterIssuer +metadata: + name: selfsigned-issuer +spec: + selfSigned: {} +``` + +This can be deployed using the following steps: +- Copy the YAML snippet above to a file called `issuer.yaml` +- Run the following command: + +```bash +kubectl -n kurrent apply -f issuer.yaml +``` + +### Self-Signed Certificate Authority + +The following example shows how a self-signed certificate authority can be generated once a [self-signed issuer](#self-signed-issuer) has been deployed: + +```yaml +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: selfsigned-ca +spec: + isCA: true + commonName: ca + subject: + organizations: + - Kurrent + organizationalUnits: + - Cloud + secretName: ca-tls + privateKey: + algorithm: RSA + encoding: PKCS1 + size: 2048 + issuerRef: + name: selfsigned-issuer + kind: ClusterIssuer + group: cert-manager.io +``` + +:::note +The values for `subject` should be changed to reflect what you require. +::: + +This can be deployed using the following steps: +- Copy the YAML snippet above to a file called `ca.yaml` +- Ensure that the `kurrent` namespace has been created +- Run the following command: + +```bash +kubectl -n kurrent apply -f ca.yaml +``` + +### Self-Signed Certificate Authority Issuer + +The following example shows how a self-signed certificate authority issuer can be generated once a [CA certificate](#self-signed-certificate-authority) has been created: + +```yaml +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: ca-issuer +spec: + ca: + secretName: ca-tls +``` + +This can be deployed using the following steps: +- Copy the YAML snippet above to a file called `ca-issuer.yaml` +- Ensure that the `kurrent` namespace has been created +- Run the following command: + +```bash +kubectl -n kurrent apply -f ca-issuer.yaml +``` + +Once this step is complete, future certificates can be generated using the self-signed certificate authority. Using k9s, +the following issuers should be visible in the `kurrent` namespace: + +![Issuers](images/certs/ca-issuer.png) + +Describing the issuer should yield: + +![Issuers](images/certs/ca-issuer-details.png) diff --git a/docs/server/kubernetes-operator/v1.3.0/operations/modify-deployments.md b/docs/server/kubernetes-operator/v1.3.0/operations/modify-deployments.md new file mode 100644 index 000000000..3a960c673 --- /dev/null +++ b/docs/server/kubernetes-operator/v1.3.0/operations/modify-deployments.md @@ -0,0 +1,118 @@ +--- +title: Modify Deployments +order: 2 +--- + +Updating KurrentDB deployments through the Operator is done by modifying the KurrentDB Custom +Resources (CRs) using standard Kubernetes tools. Most updates are processed almost immediately, but +there is special logic in place around resizing the number of replicas in a cluster. + +## Applying Updates + +`KurrentDB` instances support updates to: + +- Container Image +- Memory +- CPU +- Volume Size (increases only) +- Replicas (node count) +- Configuration + +To update the specification of a `KurrentDB` instance, simply issue a patch command via the kubectl tool. In the examples below, the cluster name is `kurrentdb-cluster`. Once patched, the Operator will take care of augmenting the underlying resources, which will cause database pods to be recreated. + +### Container Image + +```bash +kubectl -n kurrent patch kurrentdb kurrentdb-cluster --type=merge -p '{"spec":{"image": "docker.kurrent.io/kurrent-latest/kurrentdb:25.0.0"}}' +``` + +### Memory + +```bash +kubectl -n kurrent patch kurrentdb kurrentdb-cluster --type=merge -p '{"spec":{"resources": {"requests": {"memory": "2048Mi"}}}}' +``` + +### CPU + +```bash +kubectl -n kurrent patch kurrentdb kurrentdb-cluster --type=merge -p '{"spec":{"resources": {"requests": {"cpu": "2000m"}}}}' +``` + +### Volume Size + +```bash +kubectl -n kurrent patch kurrentdb kurrentdb-cluster --type=merge -p '{"spec":{"storage": {"resources": {"requests": {"storage": "2048Mi"}}}}}' +``` + +### Replicas + +```bash +kubectl -n kurrent patch kurrentdb kurrentdb-cluster --type=merge -p '{"spec":{"replicas": 3}}' +``` + +Note that the actual count of replicas in a cluster may take time to update. See [Updating Replica Count](#updating-replica-count), below. + +### Configuration + +```bash +kubectl -n kurrent patch kurrentdb kurrentdb-cluster --type=merge -p '{"spec":{"configuration": {"ProjectionsLevel": "all", "StartStandardProjections": "true"}}}' +``` + +## Updating Primary Replica Count + +A user configures the KurrentDB cluster by setting the `.spec.replicas` setting of a KurrentDB +resource. The current actual number of replicas can be observed as `.status.replicas`. The process +to grow or shrink the replicas in a cluster safely requires carefully stepping the KurrentDB +cluster through a series of consensus states, which the Operator handles automatically. + +In both cases, if the resizing flow gets stuck for some reason, you can cancel the resize by setting +`.spec.replicas` back to its original value. + +### Upsizing a KurrentDB Cluster + +The steps that the Operator takes to go from 1 to 3 nodes in a KurrentDB cluster are: + +- Take a VolumeSnapshot of pod 0 (the initial pod). +- Reconfigure pod 0 to expect a three-node cluster. +- Start a new pod 1 from the VolumeSnapshot. +- Wait for pod 0 and pod 1 to establish quorum. +- Start a new pod 2 from the VolumeSnapshot. + +Note that the database cannot process writes between the time that the Operator reconfigures pod 0 +for a three-node cluster and when pod 0 and pod 1 establish quorum. The purpose of the +VolumeSnapshot is to greatly reduce the amount of replication pod 1 must do from pod 0 before quorum +is established, which greatly reduce the amount of downtime during the resize. + +### Downsizing a KurrentDB Cluster + +The steps that the Operator takes to go from 3 nodes to 1 in a KurrentDB cluster are: + +- Make sure pod 0 and pod 1 are caught up with the leader (which may be one of them). +- Stop pod 2. +- Wait for quorum to be re-established between pods 0 and 1. +- Stop pod 1. +- Reconfigure pod 0 as a one-node cluster. + +Note that the database cannot process writes briefly after the Operator stops pod 2, and again +briefly after the Operator reconfigures pod 0. + +:::important +It is technically possible for data loss to occur when the Operator stops pod 2 if there are active +writes against the database, and either of the other two pods happen to fail at approximately the +same time pod 2 stops. + +The frequency of an environment failure should hopefully be low enough that this is not a realistic +concern. However, to reduce the risk to truly zero, you must ensure that there are no writes +against the database at the time when you downsize your cluster. +::: + +## Updating Read-Only Replica Count + +Since Read-Only Replica nodes are not electable as leaders, it is simpler to increase or decrease +the number of running read-only replicas. Still, when adding new read-only replicas, the Operator +uses VolumeSnapshots to expedite the initial catch-up reads for new read-only replicas. + +The steps that the Operator takes to increase the number of read-only replicas are: + +- Take a VolumeSnapshot of a primary node. +- Start new read-only replica node(s) based on that snapshot. diff --git a/docs/server/kubernetes-operator/versions.json b/docs/server/kubernetes-operator/versions.json index 640fbe127..10b6feb02 100644 --- a/docs/server/kubernetes-operator/versions.json +++ b/docs/server/kubernetes-operator/versions.json @@ -4,6 +4,11 @@ "basePath": "server", "group": "Kubernetes Operator", "versions": [ + { + "path": "kubernetes-operator/v1.3.0", + "version": "v1.3.0", + "startPage": "getting-started/" + }, { "path": "kubernetes-operator/v1.2.0", "version": "v1.2.0",