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 is cluster-scoped—you can deploy one operator per cluster, and the operator monitors objects across all namespaces in the cluster. Each operator installation includes an admission controller, which is a webhook that queries a REST endpoint to verify changes to mutable states in a CR instance. These components work together to deploy and maintain the state of your CRs.

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.

Helm charts

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

Quickstart installation

This quickstart section deploys the VerticaDB operator Helm chart with minimal commands. This deployment method installs the operator in the default configuration, which means the admission controller generates 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:

  1. 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!⎈
  2. 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. For example commands for additional installation scenarios, see Installing the Helm chart.

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:

  1. 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

  2. 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

  3. 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:

  1. Create a namespace for the application developer:

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

  2. 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

  3. 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

  4. 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:

  1. Install the Custom resource definitions that the operator requires. You must use the server-side=true and --force-conflicts options because the size of the CRD is too large for client-side apply operations:

    $ kubectl apply --server-side=true --force-conflicts -f https://github.com/vertica/vertica-kubernetes/releases/latest/download/verticadbs.vertica.com-crd.yaml
$ kubectl apply --server-side=true --force-conflicts -f https://github.com/vertica/vertica-kubernetes/releases/latest/download/verticaautoscalers.vertica.com-crd.yaml
$ kubectl apply --server-side=true --force-conflicts -f https://github.com/vertica/vertica-kubernetes/releases/latest/download/eventtriggers.vertica.com-crd.yaml

    For additional details about these commands, see Server-Side Apply documentation.

  2. 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.