Prepare the Kubernetes cluster

To prepare the Kubernetes cluster, perform the following tasks:

  1. Check that all prerequisites are met.
  2. Create a namespace.
  3. Install cert-manager.
  4. Install trust-manager.
  5. Install Linkerd (optional).
  6. Configure storage classes.
  7. Create the Docker registry secret.

Check that all prerequisites are met Copied

Before installing Obcerv, ensure that your Kubernetes cluster meets all the prerequisites:

You should also consult the Compatibility matrix to ensure you select compatible component versions.

Create a namespace Copied

Create or choose an existing namespace where you will install Obcerv.

kubectl create namespace itrs

Multiple instances of Obcerv can be installed in the same cluster, however there can only be one Obcerv instance in a namespace.

Install cert-manager Copied

The installation of cert-manager is required if any of the following scenarios apply:

The Obcerv Operator installs an admission webhook that requires a TLS certificate which, by default, is automatically generated by cert-manager.

Note

Although self-signed certificates are not recommended in production for encrypting externally facing connections, the Obcerv Operator’s admission webhook is an internal component that can use self-signed certificates without it being considered a security issue.

Unless your organization operates under security policies that strictly forbid self-signed certificates, you can use cert-manager for your Obcerv Operator’s webhook.

To install cert-manager, run:

helm repo add jetstack https://charts.jetstack.io
helm install cert-manager jetstack/cert-manager --set installCRDs=true -n itrs --wait

Alternatively, you can manually create TLS certificates for the Obcerv Operator’s webhook.

Manually create TLS certificates for the Obcerv Operator’s webhook Copied

Using cert-manager automates the process of creating TLS certificates and is the recommended approach for the Obcerv Operator’s webhook. Optionally, you can choose to manually create and configure a certificate by performing the following steps:

  1. Determine the following before generating your keys, certificates and Kubernetes Secrets:

    • Namespace where you will be installing the Obcerv Operator, referred to as <%namespace%> in following instructions.
    • Name of the Obcerv Operator instance, referred to as <%instance-name%> in following instructions.
    • Password you will use to protect the pkcs12 file, referred to as <%password%> in following instructions.
    • Name of the pkcs12 keystore file, referred to as <%keystore-name%> in following instructions.
  2. Use your Certificate Authority (CA) to generate an RSA private key for your webhook server.

  3. Generate a Certificate Signing Request (CSR), incorporating the fully qualified webhook service name "/CN=<%instance-name%>-webhook.<%namespace%>.svc", for the webhook private key, and sign it with the private key of the CA.

  4. Generate a pkcs12 bundle containing the webhook server key and certificate, protected with a password.

  5. Create a Kubernetes Secret containing the pkcs12 file. This secret should be prefixed with the name of the Obcerv Operator instance:

    kubectl create secret generic <%instance-name%>-webhook-tls --from-file=<%keystore-name%>=keystore.p12
    
  6. Create a Kubernetes Secret containing the password for the pkcs12 file. This secret should be prefixed with the name of the Obcerv Operator instance:

    kubectl create secret generic <%instance-name%>-webhook-tls-password --from-literal=password='<%password%>'
    
  7. Obtain the base64 encoded value of the certificate that signed the pkcs12 file and use the output as the caCertificate in your Helm values file.

    cat ca.crt | base64
    ...
    webhook.tls.caCertificate: <%...output from previous command...%>
    

Note

The value for the caCertification must be on a single line with no carriage returns.
  1. Set the following Helm values:

    webhook:
      tls:
        selfSigned: false
    
        # Default secret name containing customer provided pkcs12 file loaded in a secret.
        keystoreSecret: "<%instance-name%>-webhook-tls"
    
        # Default name of the pkcs12 file inside the above secret
        keystoreSecretKey: "<%keystore-name%>" #defaults to "keystore.p12"
    
        # Password used when generating the pkcs12 file.
        keystorePasswordSecret: "<%instance-name%>-webhook-tls-password"
    
        # Base64 encoded value of the CA certificate that signed the certification for the webhook server.
        caCertificate: ""
    

Note

If you encounter errors installing the operator after manually configuring TLS certificates, consult the Troubleshooting steps.

Install trust-manager Copied

Installing trust-manager is required only if you plan to install the Linkerd service mesh and intend to enable automatic TLS certificate rotation. The trust-manager automates the distribution of trusted certificate bundles used by Linkerd.

To install trust-manager, run:

helm install trust-manager jetstack/trust-manager --set app.trust.namespace=itrs -n itrs --wait

Install Linkerd (optional) Copied

Note

If you are installing on OpenShift OKD, you need to do the steps in Install on OpenShift OKD > Install linkerd-cni and Linkerd instead.

Linkerd is used to enable mutual TLS between the Obcerv components. TLS inside the cluster is optional and is enabled by default.

However, in a testing or proof of concept deployment you may wish to disable TLS. In this case Linkerd is not required.

Linkerd is installed in its own linkerd namespace by default.

While Linkerd automatically rotates per-proxy TLS certificates, it does not rotate the issuer certificate. Automatic rotation of the issuer certificate and its corresponding private key can be achieved using cert-manager and trust-manager with this sample configuration.

In the YAML manifest provided above, certificate duration is set at 48 hours while renewBefore is set at 25 hours, which forces the issuance of a fresh certificate 25 hours prior to the expiration of the existing one. These parameters are adjustable based on your preferences.

kubectl apply -f linkerd-certificates.yaml

Optional installation flags:

Note

If your Kubernetes cluster is version 1.25 or later, you must use Linkerd version 2.12.2 or later.

Install:

Kubernetes nodes running with docker as the container runtime (CRI) require the init container to run as root for iptables. In this case, Linkerd must be installed via --set proxyInit.runAsRoot=true.

linkerd install --crds | kubectl apply -f -

linkerd install \
--identity-external-issuer \
--set identity.externalCA=true \
| kubectl -n linkerd apply -f -

Note

If you are using Linkerd version edge-24.6.2 or above, you also need to enable proxy shutdown endpoints. To do this, run:

%> linkerd install --set proxy.enableShutdownEndpoint=true | kubectl apply -f -

Ensure all components are installed before continuing:

linkerd check

Configure storage classes Copied

Most Kubernetes clusters come with a default StorageClass pre-installed. This default StorageClass should be similar to general purpose SSD volumes on most cloud providers, such as the gp3 EBS volumes on AWS. This storage class should be configured with the default minimum gp3 settings of 3000 IOPS and 125 MiB/s throughput. For example:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gp3
provisioner: kubernetes.io/aws-ebs
parameters:
  type: "gp3"
  fsType: "ext4"
  iops: "3000"
  throughput: "125"
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true

Additionally, the Timescale workload may require higher-performing disks, specifically for large installations. These should also be similar to general purpose SSD volumes on most cloud providers, but should be configured with higher performance settings of 5000 IOPS and 200 MiB/s throughput. For example:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gp3-timescale
provisioner: ebs.csi.aws.com
parameters:
  type: "gp3"
  fsType: "ext4"
  iops: "5000"
  throughput: "200"
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true

We strongly recommend using storage classes that support automatic volume expansion so that volumes can be expanded to accommodate growth without significant downtime. We recommend against using local persistent volumes in production environments – they are viable only on single-node clusters and some persistence features that Obcerv depends on are not supported.

Create the Docker registry secret Copied

By default, Kubernetes pulls Obcerv Docker images from our Docker registry. In order to authenticate, you must create a Secret with your ITRS credentials:

kubectl create secret docker-registry itrsdocker \
  --docker-server=https://docker.itrsgroup.com \
  --docker-username=<USERNAME> \
  --docker-password=<PASSWORD> \
  -n itrs

Note

Contact your ITRS representative if you do not have the required credentials.

However, if you have elected to use an intermediary Docker registry:

Note

When the Kubernetes cluster has been prepared, you can now install the Obcerv Operator.
["Obcerv"] ["User Guide", "Technical Reference"]

Was this topic helpful?