VClusterServer custom resource definition

The VClusterServer custom resource (CR) lets the VerticaDB Operator deploy a dedicated, read-only VCluster Server inside a Kubernetes namespace for monitoring an existing OpenText™ Analytics Database database. When you apply a VClusterServer CR, the operator creates the ServiceAccount, Role, RoleBinding, Deployment, and Service needed to run the vcluster_server service. All write operations—such as adding or removing nodes—are disabled so that the VCluster Server does not interfere with the operator's own lifecycle management of the database. Certificate management for the VCluster Server in Kubernetes, including decisions about certificate rotation, is also handled through this CR.

Prerequisites

Before creating a VClusterServer CR, ensure the following:

• Deploy a VerticaDB CR with https TLS configured (spec.httpsNMATLS.secret). See [tls-kubernetes]/en/containerized/tls-kubernetes/
• Deploy a VerticaDB operator.

Create a VClusterServer CR

The VClusterServer CR declaratively creates a minimal, secure, read-only VCluster Server inside the target namespace (Deployment + Service + RBAC) so operators can run read-only NMA commands over mTLS.

The following is a minimal example that deploys a read-only VCluster Server monitoring a VerticaDB CR named my-vertica-db, defined in a YAML-formatted file named vclusterserver-example.yaml:

apiVersion: vertica.com/v1beta1
kind: VClusterServer
metadata:
  name: my-vdb
  namespace: default
spec:
  verticaDBName: my-vertica-db
  replicas: 1
  vcsTLSSecret: vcluster-server-tls
  service:
    type: ClusterIP
    port: 8665

By default, service.type is ClusterIP, which makes the VCluster Server accessible only within the cluster. To expose the endpoint outside the cluster, set service.type to NodePort or LoadBalancer.

Apply the manifest

After you create the VClusterServer CR, apply the manifest in the same namespace as the VerticaDB CR specified by verticaDBName:

$ kubectl apply -f vclusterserver-example.yaml
vclusterserver.vertica.com/my-vdb created

VDB-inherited fields

All information required for deploying and running the VClusterServer CRD is derived from the VDB specified in spec.verticaDBName. This includes:

• spec.image: The Vertica image to use.
• spec.imagePullPolicy: How often to pull the image.
• spec.serviceAccountName: Name of the ServiceAccount (can be overridden in the VCS CR).
• spec.httpsNMATLS.secret: The certificate secret for connecting to NMA.
• spec.passwordSecret: The secret for the database password.

The VClusterServer CR reacts to changes made to the VDB. Any time one of these VDB fields changes, the VCS is re-deployed using the updated value.

Kubernetes objects created by VClusterServer

When you deploy a VClusterServer CR, it creates the following additional Kubernetes objects in the same namespace: ConfigMap and Service.

ConfigMap

The operator creates a ConfigMap that the vcluster_server pod uses to retrieve cluster details. The ConfigMap name follows the pattern v-cr-name-vcluster-config:

$ kubectl get configmap | grep vcluster-config
v-vclusterserver-vcluster-config   1      47h

Service

The operator creates a Service to expose the vcluster_server endpoint. You can retrieve it by its label:

$ kubectl get service -l vertica.com/vclusterserver=vclusterserver
NAME                     TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)    AGE
vclusterserver-service   ClusterIP   10.96.10.173   <none>        8665/TCP   47h

The TYPE reflects the spec.service.type set in your VClusterServer CR (default: ClusterIP).

Accessing vcluster_server

To call vcluster_server endpoints, you need the TLS certificates that the pod uses for mutual TLS (mTLS).

Copy certificates from the pod

Copy the client certificate and key out of the running pod:

$ kubectl cp vclusterserver-7bddb6fb86-b5z82:/opt/vertica/config/vcluster_server/admin.key /tmp/admin.key
$ kubectl cp vclusterserver-7bddb6fb86-b5z82:/opt/vertica/config/vcluster_server/admin.pem /tmp/admin.pem

Replace vclusterserver-7bddb6fb86-b5z82 with the name of your running pod, which you can retrieve from the output of kubectl get pod -l vertica.com/vclusterserver=vclusterserver.

ClusterIP (port forwarding)

When spec.service.type is ClusterIP, the service is only reachable from within the cluster. Use kubectl port-forward to forward a local port to the service:

$ kubectl port-forward service/vclusterserver-service 8665:8665 &
Forwarding from 127.0.0.1:8665 -> 8665
Forwarding from [::1]:8665 -> 8665

Then call a vcluster_server endpoint using the copied certificates:

$ curl -k --cert /tmp/admin.pem --key /tmp/admin.key -X GET https://localhost:8665/v1/status | jq .
{
  "nma_status": "up",
  "nma_message": "NMA is accessible",
  "database_status": "up",
  "database_message": "Database is accessible (6 nodes UP)",
  "deployment_type": "kubernetes"
}

LoadBalancer

When spec.service.type is LoadBalancer, retrieve the external IP assigned by your cloud provider:

$ kubectl get service -l vertica.com/vclusterserver=vclusterserver
NAME                     TYPE           CLUSTER-IP     EXTERNAL-IP    PORT(S)          AGE
vclusterserver-service   LoadBalancer   10.96.10.173   <EXTERNAL-IP>  8665:XXXXX/TCP   47h

Then call a vcluster_server endpoint using the external IP directly—no port forwarding is needed:

$ curl -k --cert /tmp/admin.pem --key /tmp/admin.key -X GET https://${EXTERNAL_IP}:8665/v1/status

Monitoring VClusterServer

You can check the status of the VClusterServer CR pod by running the following command:

$ k get pod -l vertica.com/vclusterserver=vclusterserver
NAME                              READY   STATUS    RESTARTS   AGE
vclusterserver-7bddb6fb86-b5z82   1/1     Running   0          13m

You can also inspect the CR status directly:

$ kubectl get vcs vclusterserver -o json | jq .status
{
  "readyReplicas": 1,
  "totalReplicas": 1,
  "vdbConfigHash": "6144b4b5ac126e8aede209c0f8671b0889681e08221da73de4d3193c0b5d709e"
}

The status fields are: