Installing the VerticaDB operator

The custom resource definition (CRD), DB operator, and admission controller work together to maintain the state of your environment and automate tasks:.

The VerticaDB operator is a custom controller that monitors CR instances to maintain the desired state of VerticaDB objects. The operator includes an admission controller, which is a webhook that queries a REST endpoint to verify changes to mutable states in a CR instance.

By default, the operator is cluster-scoped—you can deploy one operator per cluster to monitor objects across all namespaces in the cluster. For flexibility, Vertica also provides a Helm chart deployment option that installs the operator at the namespace level.

Installation options

Vertica provides the following options to install the VerticaDB operator and admission controller:

Helm charts. Helm is a package manager for Kubernetes. The Helm chart option is the most common installation method and lets you customize your TLS configuration and environment setup. For example, Helm chart installations include operator logging levels and log rotation policy. For details about additional options, see Helm chart parameters.

Vertica also provides the Quickstart Helm chart option so that you can get started quickly with minimal requirements.
kubectl installation. Apply the Custom Resource Definitions (CRDs) and VerticaDB operator directly. You can use the kubectl tool to apply the latest CRD available on vertica-kubernetes GitHub repository.
OperatorHub.io. This is a registry that lets vendors share Kubernetes operators.

Note

Each installation option is mutually exclusive, with its own workflow that is incompatible with the other option. For example, you cannot install the VerticaDB operator with the Helm charts, and then deploy an operator in the same environment using OperatorHub.io.

Helm charts

Important

You must have cluster administrator privileges to install the operator Helm chart.

Vertica packages the VerticaDb operator and admission controller in a Helm chart. The following sections detail different installation methods so that you can install the operator to meet your environment requirements. You can customize your operator during and after installation with Helm chart parameters.

For additional details about Helm, see the Helm documentation.

Prerequisites

Kubernetes 1.21.1 and higher
Helm 3.5.0 and higher
kubectl command-line tool

Quickstart installation

The quickstart installation installs the VerticaDB Helm chart with minimal commands. This deployment installs the operator in the default configuration, which includes the following:

Cluster-scoped webhook and controllers that monitor resources across all namespaces in the cluster. For namespace-scoped deployments, see Namespace-scoped installation.
Self-signed certificates to communicate with the Kubernetes API server. If your environment requires custom certificates, see Custom certificate installation.

To quickly install the Helm chart, you must add the latest chart to your local repository and then install it in a namespace:

The add command downloads the chart to your local repository, and the update command gets the latest charts from the remote repository. When you add the Helm chart to your local chart repository, provide a descriptive name for future reference.

The following add command names the charts vertica-charts:

$ helm repo add vertica-charts https://vertica.github.io/charts
  "vertica-charts" has been added to your repositories
$ helm repo update
  Hang tight while we grab the latest from your chart repositories...
  ...Successfully got an update from the "vertica-charts" chart repository
  Update Complete. ⎈Happy Helming!⎈

Install the Helm chart to deploy the VerticaDB operator in your cluster. The following command names this chart instance vdb-op, and creates a default namespace for the operator if it does not already exist:
```
$ helm install vdb-op --namespace verticadb-operator --create-namespace vertica-charts/verticadb-operator
```

For helm install options, see the Helm documentation.

Namespace-scoped installation

By default, the VerticaDB operator is cluster-scoped. However, Vertica provides an option to install a namespace-scoped operator for environments that require more granular control over which resources an operator watches for state changes.

The VerticaDB operator includes a webhook and controllers. The webhook is cluster-scoped and verifies state changes for resources across all namespaces in the cluster. The controllers—the control loops that reconcile the current and desired states for resources—do not have a cluster-scope requirement, so you can install them at the namespace level. The namespace-scoped operator installs the webhook once at the cluster level, and then installs the controllers in the specified namespace. You can install these namespaced controllers in multiple namespaces per cluster.

Important

Do not install a mix of cluster-scoped and namespace-scoped operators in the same cluster. For example, do not install an operator with cluster-scoped controllers, and then install a namespace-scoped operator in the same cluster. This means that multiple operators serve the same CR, which results in unpredictable behavior.

To install a namespace-scoped operator, add the latest chart to your respository and issue separate commands to deploy the webhook and controllers:

The following add command names the charts vertica-charts:

$ helm repo add vertica-charts https://vertica.github.io/charts
  "vertica-charts" has been added to your repositories
$ helm repo update
  Hang tight while we grab the latest from your chart repositories...
  ...Successfully got an update from the "vertica-charts" chart repository
  Update Complete. ⎈Happy Helming!⎈

Deploy the cluster-scoped webhook and install the required CRDs. To deploy the operator as a webhook without controllers, set controllers.enable to false. The following command deploys the webhook to the vertica namespace, which is the namespace for a Vertica cluster:
```
$ helm install webhook vertica-charts/verticadb-operator --namespace vertica --set controllers.enable=false
```
Deploy the namespace-scoped operator. To prevent a second webhook installation, set webhook.enable to false. To deploy only the controllers, set controllers.scope to namespace. The following command installs the operator in the default namespace:
```
$ helm install vdb-op vertica-charts/verticadb-operator --namespace default --set webhook.enable=false,controllers.scope=namespace
```

For details about the controllers.* parameter settings, see Helm chart parameters. For helm install options, see the Helm documentation.

Custom certificate installation

The admission controller uses a webhook that communicates with the Kubernetes API over HTTPS. By default, the Helm chart generates a self-signed certificate before installing the admission controller. A self-signed certificate might not be suitable for your environment—you might require custom certificates that are signed by a trusted third-party certificate authority (CA).

To add custom certificates for the webhook:

Set the TLS key's Subjective Alternative Name (SAN) to the admission controller's fully-qualified domain name (FQDN). Set the SAN in a configuration file using the following format:
```
[alt_names]
DNS.1 = verticadb-operator-webhook-service.operator-namespace.svc
DNS.2 = verticadb-operator-webhook-service.operator-namespace.svc.cluster.local
```
Create a Secret that contains the certificates. A Secret conceals your certificates when you pass them as command-line parameters.

The following command creates a Secret named tls-secret. It stores the TLS key, TLS certificate, and CA certificate:
```
$ kubectl create secret generic tls-secret --from-file=tls.key=/path/to/tls.key --from-file=tls.crt=/path/to/tls.crt --from-file=ca.crt=/path/to/ca.crt
```
Install the Helm chart.

The add command downloads the chart to your local repository, and the update command gets the latest charts from the remote repository. When you add the Helm chart to your local chart repository, provide a descriptive name for future reference.

The following add command names the charts vertica-charts:
```
$ helm repo add vertica-charts https://vertica.github.io/charts
  "vertica-charts" has been added to your repositories
$ helm repo update
  Hang tight while we grab the latest from your chart repositories...
  ...Successfully got an update from the "vertica-charts" chart repository
  Update Complete. ⎈Happy Helming!⎈
```
When you install the Helm chart with custom certificates for the admission controller, you have to use the webhook.certSource and webhook.tlsSecret Helm chart parameters:
- webhook.certSource indicates whether you want the admission controller to install user-provided certificates. To install with custom certificates, set this parameter to secret.
- webhook.tlsSecret accepts a Secret that contains your certificates.
The following command deploys the operator with the TLS certificates and creates namespace if it does not already exist:
```
$ helm install operator-name --namespace namespace --create-namespace vertica-charts/verticadb-operator \
    --set webhook.certSource=secret \
    --set webhook.tlsSecret=tls-secret
```

Granting user privileges

After the operator is deployed, the cluster administrator is the only user with privileges to create and modify VerticaDB CRs within the cluster. To grant other users the privileges required to work with custom resources, you can leverage namespaces and Kubernetes RBAC.

To grant these privileges, the cluster administrator creates a namespace for the user, then grants that user edit ClusterRole within that namespace. Next, the cluster administrator creates a Role with specific CR privileges, and binds that role to the user with a RoleBinding. The cluster administrator can repeat this process for each user that must create or modify VerticaDB CRs within the cluster.

To provide a user with privileges to create or modify a VerticaDB CR:

Create a namespace for the application developer:

$ kubectl create namespace user-namespace
namespace/user-namespace created

Grant the application developer edit role privileges in the namespace:

$ kubectl create --namespace user-namespace rolebinding edit-access --clusterrole=edit --user=username
rolebinding.rbac.authorization.k8s.io/edit-access created

Create the Role with privileges to create and modify any CRs in the namespace. Vertica provides the verticadb-operator-cr-user-role.yaml file that defines these rules:

$ kubectl --namespace user-namespace apply -f https://github.com/vertica/vertica-kubernetes/releases/latest/download/verticadb-operator-cr-user-role.yaml
role.rbac.authorization.k8s.io/vertica-cr-user-role created

Verify the changes with kubectl get:

$ kubectl get roles --namespace user-namespace
NAME                   CREATED AT
vertica-cr-user-role   2023-11-30T19:37:24Z

Create a RoleBinding that associates this Role to the user. The following command creates a RoleBinding named vdb-access:

$ kubectl create --namespace user-namespace rolebinding vdb-access --role=vertica-cr-user-role --user=username
rolebinding.rbac.authorization.k8s.io/rolebinding created

Verify the changes with kubectl get:

$ kubectl get rolebinding --namespace user-namespace
NAME          ROLE                        AGE
edit-access   ClusterRole/edit            16m
vdb-access    Role/vertica-cr-user-role   103s

Now, the user associated with username has access to create and modify VerticaDB CRs in the isolated user-namespace.

kubectl installation

You can install the VerticaDB operator from GitHub by applying the YAML manifests with the kubectl command-line tool:

Install all Custom resource definitions. Because the size of the CRD is too large for client-side operations, you must use the server-side=true and --force-conflicts options to apply the manifests:
```
kubectl apply --server-side=true --force-conflicts -f https://github.com/vertica/vertica-kubernetes/releases/latest/download/crds.yaml
```
For additional details about these commands, see Server-Side Apply documentation.

Install the VerticaDB operator:

$ kubectl apply -f https://github.com/vertica/vertica-kubernetes/releases/latest/download/operator.yaml

OperatorHub.io

OperatorHub.io is a registry that allows vendors to share Kubernetes operators. Each vendor must adhere to packaging guidelines to simplify user adoption.

To install the VerticaDB operator from OperatorHub.io, navigate to the Vertica operator page and follow the install instructions.