Update docs for v2 release (FoundationDB#2219)

johscheuer · web-flow · commit 069f32b45216 · 2025-02-20T17:02:32.000+01:00
* Update docs for v2 release

* Update docs/manual/customization.md
diff --git a/README.md b/README.md
@@ -111,6 +111,6 @@ The makefile supports environment variables that allow you to customize your bui
 
 ## Known Limitations
 
-1. Support for backups in the operator is still in development, and there are significant missing features.
+1. Support for backups in the operator is still in development, and there are some missing features.
 1. Additional limitations can be found under [Warnings](docs/manual/warnings.md).
 1. The created FoundationDB cluster is only reachable from within the Kubernetes cluster. Except if the assigned IP addresses for the Pods are also reachable outside of the Kubernetes cluster.
diff --git a/docs/changelog/v2.0.0.md b/docs/changelog/v2.0.0.md
@@ -0,0 +1,23 @@
+# v2.0.0
+
+## Changes
+
+### Action Required
+
+Please read the required steps before upgrading in the [compatibility guide](https://github.com/FoundationDB/fdb-kubernetes-operator/blob/v0.51.1/docs/compatibility.md#preparing-for-a-major-release).
+
+### Breaking Changes
+
+* Dropped support for the `v1beta1` CRD [#2212](https://github.com/FoundationDB/fdb-kubernetes-operator/pull/2212)
+* Use locality-based exclusions per default [#2212](https://github.com/FoundationDB/fdb-kubernetes-operator/pull/2212)
+* Use DNS in cluster files per default [#2212](https://github.com/FoundationDB/fdb-kubernetes-operator/pull/2212)
+* Use the unified image per default [#2212](https://github.com/FoundationDB/fdb-kubernetes-operator/pull/2212)
+* Drop support for FDB 6.2 and 6.3 [#2212](https://github.com/FoundationDB/fdb-kubernetes-operator/pull/2212)
+* Drop support for custom PVC names [#2213](https://github.com/FoundationDB/fdb-kubernetes-operator/pull/2213)
+* Drop support for custom ConfigMap names [#2215](https://github.com/FoundationDB/fdb-kubernetes-operator/pull/2215)
+
+### Operator
+
+* Changes for the operator v2 release [#2212](https://github.com/FoundationDB/fdb-kubernetes-operator/pull/2212)
+* Ensure operator uses static names for PVC [#2213](https://github.com/FoundationDB/fdb-kubernetes-operator/pull/2213)
+* Ensure that the ConfigMap name for the cluster can't be modified [#2215](https://github.com/FoundationDB/fdb-kubernetes-operator/pull/2215)
diff --git a/docs/compatibility.md b/docs/compatibility.md
@@ -27,17 +27,18 @@ published for each major version.
 |------------------|---------------------|--------------------------|------------------------|-------------------------------|
 | 0.x              | 0.51.1              | v1beta1                  | 6.1.12+                | 1.15.0+                       |
 | 1.x              | -                   | v1beta1,v1beta2          | 6.2.20+                | 1.19.0+                       |
+| 2.x              | -                   | v1beta2                  | 7.1.0+                 | 1.19.0+                       |
 
-Note that the base operator image only supports a single version of FoundationDB. For more information about using different versions of FoundationDB, see the [Operator Customization](/docs/manual/operator_customization.md) guide in the user manual.
+Note that the base operator image only supports a single version of FoundationDB.
+For more information about using different versions of FoundationDB, see the [Operator Customization](/docs/manual/operator_customization.md) guide in the user manual.
 
 ## Preparing for a Major Release
 
 Before you upgrade to a new major version, you should first update the operator
 and the CRD to the most recent release for the major version you are currently
 running. You can find that release in the table above. This will ensure that you
 can opt in to new behavior and move to the latest supported fields in the spec
-in advance of the upgrade, through whatever process you need to update your
-clusters safely.
+in advance of the upgrade, through whatever process you need to update your clusters safely.
 After you updated the operator you should ensure that all clusters are in a reconciled state and all changes are applied.
 
 At this point, you can use the `kubectl-fdb` plugin to check your cluster specs for deprecated fields or defaults.
diff --git a/docs/manual/backup.md b/docs/manual/backup.md
@@ -6,7 +6,7 @@ You can restore to any point in time after the end of the first snapshot.
 
 You can find more information about the backup feature in the [FoundationDB Backup documentation](https://apple.github.io/foundationdb/backups.html).
 
-**Warning**: Support for backups in the operator is still in development, and there are significant missing features.
+**Warning**: Support for backups in the operator is still in development, and there are some missing features.
 
 ## Example Backup
 
diff --git a/docs/manual/customization.md b/docs/manual/customization.md
@@ -2,11 +2,19 @@
 
 This document covers some of the options the operator provides for customizing your FoundationDB deployment.
 
-Many of these customizations involve the `processes` field in the cluster spec, which we will refer to as the "process settings". This field is a dictionary, mapping a process class to a process settings object. This also supports a special key called `general` which is applied to all process classes. If a value is specified for a specific process class, the `general` value will be ignored. These values are merged at the top level of the process settings object. If you specify a `volumeClaimTemplate` object in the `storage` settings and a `podTemplate` object in the `general` settings, the storage processes will use both the custom `volumeClaimTemplate` and the general `podTemplate`. If you specify a `podTemplate` object in the `storage` settings and `podTemplate` object in the `general` settings, the storage processes will only use the values given in the `storage` settings, and will ignore the pod template from the `general` settings completely.
+Many of these customizations involve the `processes` field in the cluster spec, which we will refer to as the "process settings".
+This field is a dictionary, mapping a process class to a process settings object.
+This also supports a special key called `general` which is applied to all process classes.
+If a value is specified for a specific process class, the `general` value will be ignored.
+These values are merged at the top level of the process settings object.
+If you specify a `volumeClaimTemplate` object in the `storage` settings and a `podTemplate` object in the `general` settings, the storage processes will use both the custom `volumeClaimTemplate` and the general `podTemplate`.
+If you specify a `podTemplate` object in the `storage` settings and `podTemplate` object in the `general` settings, the storage processes will only use the values given in the `storage` settings, and will ignore the pod template from the `general` settings completely.
 
 ## Running Multiple Storage Servers per Pod
 
-Since FoundationDB is limited to a single core it can make sense to run multiple storage server per disk. You can change the number of storage server per Pod with the `storageServersPerPod` setting. This will start multiple FDB processes inside of a single container, under a single `fdbmonitor` process.
+Since FoundationDB is limited to a single core it can make sense to run multiple storage server per disk.
+You can change the number of storage server per Pod with the `storageServersPerPod` setting.
+This will start multiple FDB processes inside of a single container, under a single `fdbmonitor` process.
 
 ```yaml
 apiVersion: apps.foundationdb.org/v1beta2
@@ -19,7 +27,7 @@ spec:
     storageServersPerPod: 2
 ```
 
-A change to the `storageServersPerPod` will replace all of the storage pods. For more information about this feature read the [multiple storage servers per pod](/docs/design/implemented/multiple_storage_per_disk.md) design doc.
+A change to the `storageServersPerPod` will replace all the storage pods. For more information about this feature read the [multiple storage servers per pod](/docs/design/implemented/multiple_storage_per_disk.md) design doc.
 
 ## Customizing the Volumes
 
@@ -244,88 +252,6 @@ Using service IPs presents its own challenges:
 * We currently only support services with the ClusterIP type. These IPs may not be routable from outside the Kubernetes cluster.
 * The Service IP space is often more limited than the pod IP space, which could cause you to run out of service IPs.
 
-## Using DNS
-
-Using Pod IPs has the limitation that Pods might get a new IP address if they are recreated and sometimes using service IPs is not the right approach.
-FDB supports to use DNS in the cluster file since 7.1 and the operator can make use of that.
-
-*Note*: This requires the following customization to inject the 7.1 library and use it as primary library (see code example below).
-As an alternative you can build the operator image by yourself that contains the 7.1 library as the primary library.
-Building the operator by yourself can be achieved with `docker build --build-arg FDB_VERSION=7.1.26 -t foundationdb/fdb-kubernetes-operator .`.
-
-```yaml
-      initContainers:
-         ...
-         # Install this library in a special location to force the operator to
-         # use it as the primary library.
-         - name: foundationdb-kubernetes-init-7-1-primary
-           image: foundationdb/foundationdb-kubernetes-sidecar:7.1.26-1
-           args:
-             - "--copy-library"
-             - "7.1"
-             - "--output-dir"
-             - "/var/output-files/primary"
-             - "--init-mode"
-           volumeMounts:
-             - name: fdb-binaries
-               mountPath: /var/output-files
-      containers:
-         - name: manager
-           imagePullPolicy: IfNotPresent
-           env:
-             - name: LD_LIBRARY_PATH
-               value: /usr/bin/fdb/primary/lib
-```
-
-The important part here is to add an additional init container with the 7.1 version and copy the library into `.../primary`, this library will be used by the operator as primary library.
-Once you set `useDNSInClusterFile` to true the operator will make the required changes to use DNS instead of IPs in the cluster file.
-
-```yaml
-apiVersion: apps.foundationdb.org/v1beta2
-kind: FoundationDBCluster
-metadata:
-    name: sample-cluster
-spec:
-  version: 7.1.26
-  routing:
-    useDNSInClusterFile: true
-```
-
-The generated connection string will look like this:
-
-```bash
-$ kubectl get cm test-cluster-config  -o jsonpath='{.data.cluster-file}'
-test_cluster:YeA03hA3hSC9vRnc2snrHf9o3rOZHe8o@test-cluster-storage-1.test-cluster.default.svc.cluster.local:4501,test-cluster-storage-2.test-cluster.default.svc.cluster.local:4501,test-cluster-storage-3.test-cluster.default.svc.cluster.local:4501
-```
-
-and the status command will show that the coordianators are resolved using the DNS names:
-
-```bash
-$ fdbcli --exec 'status details'
-Using cluster file `/var/dynamic-conf/fdb.cluster'.
-
-Configuration:
-...
-
-Coordination servers:
-  test-cluster-storage-1.test-cluster.default.svc.cluster.local:4501  (reachable)
-  test-cluster-storage-2.test-cluster.default.svc.cluster.local:4501  (reachable)
-  test-cluster-storage-3.test-cluster.default.svc.cluster.local:4501  (reachable)
-```
-
-The operator will add a special locality to the fdbserver processes called `dns_name` which stores the dns name for this process:
-
-```json
-     "locality" : {
-                    "dns_name" : "test-cluster-storage-3.test-cluster.default.svc.cluster.local",
-                    "instance_id" : "storage-3",
-                    "machineid" : "test-cluster-storage-3",
-                    "processid" : "fb1980fe9c2a6aef589ea0fd5c6131a2",
-                    "zoneid" : "test-cluster-storage-3"
-                },
-
-```
-
 ## Using Multiple Namespaces
 
 Our [sample deployment](../../config/samples/deployment.yaml) configures the operator to run in single-namespace mode, where it only manages resources in the namespace where the operator itself is running. If you want a single deployment of the operator to manage your FDB clusters across all of your namespaces, you will need to run it in global mode. Which mode is appropriate will depend on the constraints of your environment.
@@ -508,8 +434,8 @@ kubectl label pod,pvc,configmap,service -l foundationdb.org/fdb-cluster-name=sam
 The operator currently supports two different image types: a split image and a unified image.
 The split image provides two different images for the `foundationdb` container and the `foundationdb-kubernetes-sidecar` container.
 The unified image provides a single image which handles launching `fdbserver` processes as well as providing feedback to the operator on locality information and updates to dynamic conf.
-The default behavior in the operator is to use the split image.
-To switch to the unified image, set the flag in the cluster spec as follows:
+The default behavior in the operator is to use the unified image.
+To switch to the split image, set the flag in the cluster spec as follows:
 
 ```yaml
 apiVersion: apps.foundationdb.org/v1beta2
@@ -518,9 +444,11 @@ metadata:
   name: sample-cluster
 spec:
   version: 7.1.26
-  imageType: "unified"
+  imageType: "split"
 ```
 
+**NOTE**: The split image is deprecated and new features will only be implemented in the unified image.
+
 For more information on how the interaction between the operator and these images works, see the [technical design](technical_design.md#interaction-between-the-operator-and-the-pods).
 
 ## Next
diff --git a/docs/manual/fault_domains.md b/docs/manual/fault_domains.md
@@ -379,7 +379,7 @@ Once that change is fully reconciled, you can clear the deny list from the spec.
 
 [Pod disruption budgets](https://kubernetes.io/docs/tasks/run-application/configure-pdb/)
 are a good idea to prevent simultaneous disruption to many components in a
-cluster, particularly during the upgrade of nodepools in public clouds. The
+cluster, particularly during the upgrade of node pools in public clouds. The
 operator does not yet create these automatically. To aid in creation of PDBs the
 operator preferentially selects coordinators from just storage pods, then if
 there are not enough storage pods, or the storage pods are not spread across
diff --git a/docs/manual/getting_started.md b/docs/manual/getting_started.md
@@ -67,6 +67,9 @@ As an example, we are going to deploy a [Kubernetes Job](https://kubernetes.io/d
 The `cluster file` is available through the exposed `ConfigMap` that can be used as follows:
 
 ```yaml
+# TODO update this example with the unified image
+
+
 apiVersion: batch/v1
 kind: CronJob
 metadata:
@@ -83,19 +86,22 @@ spec:
           # can write too. This ensures that long-running applications will keep the cluster-file updated
           # if the coordinators change.
           - name: init-cluster-file
-            image: foundationdb/foundationdb-kubernetes-sidecar:7.1.26-1
+            image: foundationdb/fdb-kubernetes-monitor:7.1.26
             args:
               # Make sure the sidecar exits when the file is not empty and was successfully copied.
-              - --init-mode
+              - --mode
+              - init
               - --input-dir
               - /mnt/config-volume
+              - --output-dir
+              - /out-dir
               # Only copy the cluster-file that is provided by the ConfigMap
               - --copy-file
               - cluster-file
               # Make sure the cluster-file is not empty.
               - --require-not-empty
               - cluster-file
-          volumeMounts:
+            volumeMounts:
             - name: config-volume
               mountPath: /mnt/config-volume
             - name: shared-volume
diff --git a/docs/manual/operations.md b/docs/manual/operations.md
@@ -17,7 +17,10 @@ The operator uses the `locality_instance_id` to identify the process from the [m
 
 ## Replacing a Process
 
-If you delete a pod, the operator will automatically create a new pod to replace it. If there is a volume available for re-use, we will create a new pod to match that volume. This means that in general you can replace a bad process just by deleting the pod. This may not be desirable in all situations, as it creates a loss of fault tolerance until the replacement pod is created. This also requires that the original volume be available, which may not be possible in some failure scenarios.
+If you delete a pod, the operator will automatically create a new pod to replace it. If there is a volume available for re-use, we will create a new pod to match that volume.
+This means that in general you can replace a bad process just by deleting the pod.
+This may not be desirable in all situations, as it creates a loss of fault tolerance until the replacement pod is created.
+This also requires that the original volume be available, which may not be possible in some failure scenarios.
 
 As an alternative, you can replace a pod by explicitly placing it in the `processGroupsToRemove` list:
 
@@ -98,13 +101,13 @@ spec:
 ```
 
 The default value for the log group of the operator is `fdb-kubernetes-operator` but can be changed by setting the environment variable `FDB_NETWORK_OPTION_TRACE_LOG_GROUP`.
-The operator version `v1.19.0` and never sets this value as a default and those changes are not required.
+The operator version `v1.19.0` and newer sets this value as a default and those changes are not required.
 
 The upgrade process is described in more detail in [upgrades](./upgrades.md).
 
 ## Renaming a Cluster
 
-The name of a cluster is immutable, and it is included in the names of all of the dependent resources, as well as in labels on the resources.
+The name of a cluster is immutable, and it is included in the names of all the dependent resources, as well as in labels on the resources.
 If you want to change the name later on, you can do so with the following steps.
 This example assumes you are renaming the cluster `sample-cluster` to `sample-cluster-2`.
 
diff --git a/docs/manual/operator_customization.md b/docs/manual/operator_customization.md
diff --git a/docs/manual/warnings.md b/docs/manual/warnings.md
