feat: add LinkedDatabase CRD

PROJECT

@@ -24,6 +24,15 @@ resources:
     defaulting: true
     validation: true
     webhookVersion: v1
+- api:
+    crdVersion: v1
+    namespaced: true
+  controller: true
+  domain: nutanix.com
+  group: ndb
+  kind: LinkedDatabase
+  path: github.com/nutanix-cloud-native/ndb-operator/api/v1alpha1
+  version: v1alpha1
 - api:
     crdVersion: v1
     namespaced: true

README.md

@@ -64,7 +64,7 @@ The container and bundle image creation steps can be skipped if existing images
 
 ## Usage
 
-**NDBServer and credentials:** The operator uses two custom resources—**NDBServer** (cluster-scoped) and **Database** (namespaced). **NDBServer** is cluster-scoped so that admins can store the NDB API credential secret in a restricted namespace (e.g. `ndb-credentials`) and set `credentialSecretRef` to point to it. Developers who create **Database** resources only need to reference the NDBServer by **name** in `ndbRef` (e.g. `ndbRef: ndb`); they can list and use cluster-scoped NDBServers without needing access to the secret's namespace.
+**NDBServer and credentials:** The operator uses **NDBServer** (cluster-scoped) plus namespaced workload resources such as **Database** and **LinkedDatabase**. **NDBServer** is cluster-scoped so that admins can store the NDB API credential secret in a restricted namespace (e.g. `ndb-credentials`) and set `credentialSecretRef` to point to it. Developers who create **Database** or **LinkedDatabase** resources only need to reference the NDBServer by **name** in `ndbRef` (e.g. `ndbRef: ndb`); they can list and use cluster-scoped NDBServers without needing access to the secret's namespace.
 
 **Supported Database Engines:**
 - PostgreSQL
@@ -521,6 +521,46 @@ Create the Database resource:
 kubectl apply -f <path/to/database-manifest.yaml>
 ```
 
+### Creating a linked PostgreSQL database on an existing instance
+
+Use `LinkedDatabase` when you need to add a logical PostgreSQL database to an existing NDB PostgreSQL instance without provisioning a new database server VM.
+
+The operator maps this resource to:
+
+```sh
+POST /databases/<sourceDatabaseId>/linked-databases
+```
+
+with a request body like:
+
+```json
+{"databases":[{"databaseName":"appdb"}]}
+```
+
+Example:
+
+```yaml
+apiVersion: ndb.nutanix.com/v1alpha1
+kind: LinkedDatabase
+metadata:
+  name: appdb
+  namespace: default
+spec:
+  # Name of the cluster-scoped NDBServer resource
+  ndbRef: ndb
+  # Use either sourceDatabaseId or sourceDatabaseName.
+  sourceDatabaseName: existing-postgres-instance
+  # sourceDatabaseId: "<existing-postgres-instance-uuid>"
+  databaseName: appdb
+```
+
+Create the linked database resource:
+
+```sh
+kubectl apply -f <path/to/linked-database-manifest.yaml>
+kubectl get linkeddatabases -n default
+```
+
 ### Additional Arguments for Databases
 Below are the various optional addtionalArguments you can specify along with examples of their corresponding values. Arguments that have defaults will be indicated.
 

api/v1alpha1/linked_database_types.go

@@ -0,0 +1,81 @@
+/*
+Copyright 2022-2023 Nutanix, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package v1alpha1
+
+import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+
+// LinkedDatabaseSpec defines the desired state of LinkedDatabase.
+// +kubebuilder:validation:XValidation:rule="(has(self.sourceDatabaseId) && size(self.sourceDatabaseId) > 0) || (has(self.sourceDatabaseName) && size(self.sourceDatabaseName) > 0)",message="Either sourceDatabaseId or sourceDatabaseName must be provided"
+type LinkedDatabaseSpec struct {
+	// Name of the cluster-scoped NDBServer resource.
+	// +kubebuilder:validation:Required
+	// +kubebuilder:validation:MinLength=1
+	NDBRef string `json:"ndbRef"`
+	// UUID of the existing NDB database instance to add a linked database to.
+	// Either sourceDatabaseId or sourceDatabaseName must be provided.
+	// +optional
+	// +kubebuilder:validation:MinLength=1
+	SourceDatabaseId string `json:"sourceDatabaseId,omitempty"`
+	// Name of the existing NDB database instance to add a linked database to.
+	// Either sourceDatabaseId or sourceDatabaseName must be provided.
+	// +optional
+	// +kubebuilder:validation:MinLength=1
+	SourceDatabaseName string `json:"sourceDatabaseName,omitempty"`
+	// Name of the logical database to create on the existing database instance.
+	// +kubebuilder:validation:Required
+	// +kubebuilder:validation:MinLength=1
+	DatabaseName string `json:"databaseName"`
+}
+
+// LinkedDatabaseStatus defines the observed state of LinkedDatabase.
+type LinkedDatabaseStatus struct {
+	Status              string `json:"status,omitempty"`
+	SourceDatabaseId    string `json:"sourceDatabaseId,omitempty"`
+	LinkedDatabaseId    string `json:"linkedDatabaseId,omitempty"`
+	CreationOperationId string `json:"creationOperationId,omitempty"`
+	Message             string `json:"message,omitempty"`
+}
+
+// +kubebuilder:object:root=true
+// +kubebuilder:subresource:status
+// +kubebuilder:resource:shortName={"ldb","ldbs"}
+// +kubebuilder:printcolumn:name="Status",type=string,JSONPath=`.status.status`
+// +kubebuilder:printcolumn:name="Source Database ID",type=string,JSONPath=`.status.sourceDatabaseId`
+// +kubebuilder:printcolumn:name="Linked Database ID",type=string,JSONPath=`.status.linkedDatabaseId`
+// +kubebuilder:printcolumn:name="Database Name",type=string,JSONPath=`.spec.databaseName`
+
+// LinkedDatabase is the Schema for the linkeddatabases API.
+type LinkedDatabase struct {
+	metav1.TypeMeta   `json:",inline"`
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	Spec   LinkedDatabaseSpec   `json:"spec,omitempty"`
+	Status LinkedDatabaseStatus `json:"status,omitempty"`
+}
+
+// +kubebuilder:object:root=true
+
+// LinkedDatabaseList contains a list of LinkedDatabase.
+type LinkedDatabaseList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata,omitempty"`
+	Items           []LinkedDatabase `json:"items"`
+}
+
+func init() {
+	SchemeBuilder.Register(&LinkedDatabase{}, &LinkedDatabaseList{})
+}

config/crd/bases/ndb.nutanix.com_linkeddatabases.yaml

@@ -0,0 +1,106 @@
+---
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  annotations:
+    controller-gen.kubebuilder.io/version: v0.18.0
+  name: linkeddatabases.ndb.nutanix.com
+spec:
+  group: ndb.nutanix.com
+  names:
+    kind: LinkedDatabase
+    listKind: LinkedDatabaseList
+    plural: linkeddatabases
+    shortNames:
+    - ldb
+    - ldbs
+    singular: linkeddatabase
+  scope: Namespaced
+  versions:
+  - additionalPrinterColumns:
+    - jsonPath: .status.status
+      name: Status
+      type: string
+    - jsonPath: .status.sourceDatabaseId
+      name: Source Database ID
+      type: string
+    - jsonPath: .status.linkedDatabaseId
+      name: Linked Database ID
+      type: string
+    - jsonPath: .spec.databaseName
+      name: Database Name
+      type: string
+    name: v1alpha1
+    schema:
+      openAPIV3Schema:
+        description: LinkedDatabase is the Schema for the linkeddatabases API.
+        properties:
+          apiVersion:
+            description: |-
+              APIVersion defines the versioned schema of this representation of an object.
+              Servers should convert recognized schemas to the latest internal value, and
+              may reject unrecognized values.
+              More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
+            type: string
+          kind:
+            description: |-
+              Kind is a string value representing the REST resource this object represents.
+              Servers may infer this from the endpoint the client submits requests to.
+              Cannot be updated.
+              In CamelCase.
+              More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
+            type: string
+          metadata:
+            type: object
+          spec:
+            description: LinkedDatabaseSpec defines the desired state of LinkedDatabase.
+            properties:
+              databaseName:
+                description: Name of the logical database to create on the existing
+                  database instance.
+                minLength: 1
+                type: string
+              ndbRef:
+                description: Name of the cluster-scoped NDBServer resource.
+                minLength: 1
+                type: string
+              sourceDatabaseId:
+                description: |-
+                  UUID of the existing NDB database instance to add a linked database to.
+                  Either sourceDatabaseId or sourceDatabaseName must be provided.
+                minLength: 1
+                type: string
+              sourceDatabaseName:
+                description: |-
+                  Name of the existing NDB database instance to add a linked database to.
+                  Either sourceDatabaseId or sourceDatabaseName must be provided.
+                minLength: 1
+                type: string
+            required:
+            - databaseName
+            - ndbRef
+            type: object
+            x-kubernetes-validations:
+            - message: Either sourceDatabaseId or sourceDatabaseName must be provided
+              rule: (has(self.sourceDatabaseId) && size(self.sourceDatabaseId) > 0)
+                || (has(self.sourceDatabaseName) && size(self.sourceDatabaseName)
+                > 0)
+          status:
+            description: LinkedDatabaseStatus defines the observed state of LinkedDatabase.
+            properties:
+              creationOperationId:
+                type: string
+              linkedDatabaseId:
+                type: string
+              message:
+                type: string
+              sourceDatabaseId:
+                type: string
+              status:
+                type: string
+            type: object
+        type: object
+    served: true
+    storage: true
+    subresources:
+      status: {}

config/crd/kustomization.yaml

@@ -3,6 +3,7 @@
 # It should be run by config/default
 resources:
 - bases/ndb.nutanix.com_databases.yaml
+- bases/ndb.nutanix.com_linkeddatabases.yaml
 - bases/ndb.nutanix.com_ndbservers.yaml
 #+kubebuilder:scaffold:crdkustomizeresource
 

config/rbac/role.yaml

@@ -43,6 +43,7 @@ rules:
   - ndb.nutanix.com
   resources:
   - databases
+  - linkeddatabases
   - ndbservers
   verbs:
   - create
@@ -63,6 +64,7 @@ rules:
   - ndb.nutanix.com
   resources:
   - databases/status
+  - linkeddatabases/status
   - ndbservers/status
   verbs:
   - get