Installing the Vertica DB operator

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

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

  • The CRD extends the Kubernetes API to provide custom objects. It serves as a blueprint for custom resource (CR) instances that specify the desired state of your environment.

  • The VerticaDB operator is a custom controller that monitors CR instances to maintain the desired state of VerticaDB objects. You can deploy one VerticaDB operator per namespace, and the operator monitors only the VerticaDB objects within that namespace.

  • The admission controller is a webhook that queries a REST endpoint to verify changes to mutable states in a CR instance.

Prerequisites

Installation options

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

Helm charts

Vertica packages VerticaDB operator and admission controller in a Helm chart. Vertica on Kubernetes allows one operator instance per namespace.

Configuring TLS for the admission controller

Before you can install the VerticaDB Helm chart, you must configure TLS for the admission controller. The admission controller uses a webhook that requires TLS certificates for data encryption. Use the webhook.certSource Helm chart parameter to manage the TLS certificates.

By default, webhook.certSource is set to internal, a setting that generates a self-signed certificate before starting the admission controller. There are two additional settings that require manual configuration before you install the operator:

  • secret: You generate custom certificates before you create the Helm chart and store them in a Secret. This option requires that you set the webhook.tlsSecret Helm chart parameter.
  • cert-manager: Deprecated. You install the cert-manager operator, and it generates self-signed certificates. When the certificate nears expiration, cert-manager automatically handles private key rotation.

Defining custom certificates

Custom certificates require a TLS key that sets the Subjective Alternative Name (SAN) using the admission controller webhook's fully-qualified domain name (FDQN). You can set the SAN in a configuration file with the following format:

[alt_names]
DNS.1 = verticadb-operator-webhook-service.namespace.svc
DNS.2 = verticadb-operator-webhook-service.namespace.svc.cluster.local

For more information about TLS and Vertica, see TLS protocol.

When you install the VerticaDB operator and admission controller Helm chart, you can pass parameters to customize the Helm chart. Conceal custom certificates in a Secret before you pass them as parameters. The following command creates a Secret that 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

Use tls-secret when you install the VerticaDB operator and admission controller Helm chart. For a detailed example, see Helm chart parameters.

Installing cert-manager

cert-manager is available as a YAML manifest in a GitHub repository:

  1. Use kubectl to install cert-manager:

    $ kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.5.3/cert-manager.yaml

    Installation might take a few minutes.

  2. Verify the cert-manager installation:

    $ kubectl get pods --namespace cert-manager
NAME                                       READY   STATUS    RESTARTS   AGE
cert-manager-7dd5854bb4-skks7              1/1     Running   5          12d
cert-manager-cainjector-64c949654c-9nm2z   1/1     Running   5          12d
cert-manager-webhook-6bdffc7c9d-b7r2p      1/1     Running   5          12d

  3. When you install the Helm chart, set the webhook.certSource Helm chart parameter to cert-manager:

    $ helm install operator-name --namespace namespace --create-namespace vertica-charts/verticadb-operator \
  --set webhook.certSource=cert-manager

For additional details about cert-manager install verification, see the cert-manager documentation.

Granting operator privileges

Optionally, you can authorize a user without cluster administrator privileges to install the operator in a specific namespace. You can grant these operator privileges with a preconfigured Kubernetes service account.

Vertica leverages Kubernetes RBAC to authorize a service account with operator privileges to perform operator actions. You can grant these privileges to a Role resource type, then define a RoleBinding resource type that associates that Role with a ServiceAccount.

After the cluster administrator binds that ServiceAccount to a namespace, any user can perform operator actions if they install the Helm chart with the ServiceAccount.

Cluster administrator set up

The cluster administrator creates a namespace and then binds to it a service account with the required operator privileges:

  1. Install the CRDs from the vertica-kubernetes GitHub repository:

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

  2. Create a namespace:

    $ kubectl create namespace namespace

  3. Apply the ServiceAccount, Roles, and RoleBindings required to grant operator privileges to a service account.

    The following command applies operator-rbac.yaml, a sample file that defines the required operator privileges:

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

  4. Verify the changes with kubectl get:

    • ServiceAccount:

      $ kubectl get serviceaccounts -n namespace
NAME                                    SECRETS   AGE
default                                 1         71m
verticadb-operator-controller-manager   1         69m

    • Roles in the correct namespace:

      $ kubectl get roles -n namespace
NAME                                      CREATED AT
verticadb-operator-leader-election-role   2022-04-14T16:26:53Z
verticadb-operator-manager-role           2022-04-14T16:26:53Z

    • RoleBindings in the correct namespace:

      $ kubectl get rolebinding -n namespace
NAME                                             ROLE                                           AGE
verticadb-operator-leader-election-rolebinding   Role/verticadb-operator-leader-election-role   73m
verticadb-operator-manager-rolebinding           Role/verticadb-operator-manager-role           73m

Non-cluster administrator installation

Any user can perform operator actions if they use the serviceAccountOverride parameter to install the helm chart with the ServiceAccount with privileges.

  1. Add the Vertica helm charts to your repository. The following command installs the CRD Helm chart and names it vertica-charts for future reference:

    $ helm repo add vertica-charts https://vertica.github.io/charts

  2. Update your Helm repository to ensure that you are using the latest version of your repository:

    $ helm repo update
  1. Install the operator: 
    $ helm install vdb-op -n namespace vertica-charts/verticadb-operator \
  --skip-crds \
  --set webhook.enable=false \
  --set prometheus.createProxyRBAC=false \
  --set skipRoleAndRoleBindingCreation=true \
  --set serviceAccountNameOverride=verticadb-operator-controller-manager

Installing the helm chart

Before you can install the Helm chart, you must select a method to configure TLS for the admission controller.

The following install steps use custom certificates:

  1. Add the Vertica helm charts to your repository. The following command installs the CRD Helm chart and names it vertica-charts for future reference:

    $ helm repo add vertica-charts https://vertica.github.io/charts

  2. Update your Helm repository to ensure that you are using the latest version of your repository:

    $ helm repo update

  1. Install the operator Helm chart. The following examples demonstrate the most common Helm chart configurations. For details about the Helm chart options and parameters, see Helm chart parameters.

    Enter one of the following commands to customize your Helm chart installation:

    • Default configuration. The following command requires cluster administrator privileges:

      $ helm install operator-name --namespace namespace --create-namespace vertica-charts/verticadb-operator

    • Custom certificates. Pass custom certificates with the webhook.caBundle, webhook.certSource, and webhook.tlsSecret. The following command requires cluster administrator privileges, and uses the tls-secret Secret created in Defining Custom Certificates:

      $ helm install operator-name --namespace namespace --create-namespace vertica-charts/verticadb-operator \
  --set webhook.certSource=secret \
  --set webhook.tlsSecret=tls-secret

    • Service account override. Use service accounts to allow users without cluster administrator privileges to install the operator. Pass the service account with the serviceAccountNameOverride parameter:

      $ helm install operator-name --namespace namespace --create-namespace vertica-charts/verticadb-operator \
    --set serviceAccountNameOverride=service-account-name

      For details, see Granting Operator Installation Privileges.

    • Do not install the admission controller webhook. Deploying the webhook requires cluster-scoped privileges that are not required to install the operator. If you use a service account that is granted the privileges required to install the operator but not the webhook, provide the service account with serviceAccountNameOverride, and set webhook.enable to false to deploy only the operator:

      $ helm install operator-name --namespace namespace --create-namespace vertica-charts/verticadb-operator \
    --set serviceAccountNameOverride=service-account-name
    --set webhook.enable=false

For additional details about helm install, see the official documentation.

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.