Link Search Menu Expand Document Documentation Menu
Documentation

Lucenia Search Installation Quickstart

This quickstart guide will help you get started with Lucenia Search with Helm in a Kubernetes cluster.

Prerequisites

  • A Kubernetes cluster
  • Helm 3.x
  • kubectl

Installation

Install Lucenia Search with the Demo Security Configuration

This section walks through deployting Lucenia Search with the demo security configuration and license. The license is required to run Lucenia Search. The demo security configuration includes a default admin user with the username admin and a randomly generated password. This setup is for demonstration purposes only. For production deployments, you should use a custom security configuration.

Reference the lucenia Helm Chart for detailed information on the default values and configuration options.

  1. Add the Lucenia Search Helm repository:

     helm repo add lucenia https://lucenia.github.io/helm-charts
 helm repo update

  2. Update the values to install Lucenia Search with the demo security configuration and license:

    1. An initial admin password is required to install Lucenia Search. The following command generates a strong random password which can be used for the LUCENIA_INITIAL_ADMIN_PASSWORD value:

       openssl rand -base64 32

    2. Create your namespace if it does not exist:

       export NS=<your-namespace>
 kubectl create namespace $NS

    3. Create a secret with the license:

       kubectl --namespace $NS create secret generic license-cert --from-file=trial.crt

    4. Then, update the values to set the initial admin password, mount the license certificate secret in $LUCENIA_HOME/config/license and set its filepath in the lucenia.yml config:

      1. Add the following to the values file:

         extraEnvs:
 - name: LUCENIA_INITIAL_ADMIN_PASSWORD
   value: "<your-password>"

 secretMounts:
 - name: license-cert
   secretName: license-cert
   path: /usr/share/lucenia/config/license

      2. Add the license certificate filepath to the config. Locate config in values file; the lucenia.yml file’s plugins should be updated to include license.certificate_filepath, with its value containing the path to the license certificate:

         config:
   lucenia.yml: |
     plugins:
       license:
         certificate_filepath: config/license/trial.crt

      Note that during this step, we use the license-cert secret name and the trial.crt filename for the certificate. If you used a different secret name, you should update the values file accordingly.

      We also mount the license certificate secret in the /usr/share/lucenia/config/license path. If your luceniaHome value is different, you should update the values file accordingly.

    5. Install the Lucenia Search Helm chart:

       helm install <my-lucenia-deployment> lucenia/lucenia --version 0.1.0 --namespace $NS --values my-values.yaml

Install Lucenia Search with Custom Security Configuration

This section walks through replacing the demo configuration for Lucenia Search with custom security configuration and certificates. The license is required to run Lucenia Search.

  1. Create certificates for the custom security configuration using one of the following methods:

    • Create self-signed certificates using openssl. Reference the Create Self-Signed Certificates section for more information.
    • Use a certificate authority (CA) to sign the certificates. This is outside the scope of this guide.

  2. Edit the following keys within lucenia.yml security plugin configuration in values.yaml to use the custom certificates. The following keys should be updated with the custom certificate filepaths, authcz, and nodes distinguished names (DNs):

     config:
 lucenia.yml: |
     plugins:
     security:
         ssl:
         transport:
             pemcert_filepath: certs/mynode.pem
             pemkey_filepath: certs/mynode-key.pem
             pemtrustedcas_filepath: certs/root-ca.pem
             enforce_hostname_verification: false
         http:
             enabled: true
             pemcert_filepath: certs/mynode.pem
             pemkey_filepath: certs/mynode-key.pem
             pemtrustedcas_filepath: certs/root-ca.pem
         authcz:
           admin_dn:
             - CN=admin.dns.a-record,O=Example,ST=CA,C=US
         nodes_dn:
           - CN=mynode.dns.a-record,O=Example,ST=CA,C=US

    In the event certificates have been created for multiple nodes, nodes_dn should have a list of distinguished names for each node. If hostname verification is enabled, the Common Name (CN) must match the DNS A record for the CSR. If you use the same node certificate on all nodes, or do not have a CN for each CSR that matches the DNS A record, set enforce_hostname_verification to false.

  3. Create a secret and update the values.yaml to mount your custom certificates:

    1. Create a secret with the custom certificates:

       kubectl create secret generic lucenia-certs --from-file=admin.pem,admin-key.pem,mynode.pem,mynode-key.pem,root-ca.pem

    2. Update the values to mount the custom certificates:

      1. Add the following to the values file:

           - name: custom-certs
     secretName: lucenia-certs
     path: /usr/share/lucenia/config/certs

  4. Confirm Lucenia pods are running with the command kubectl get pods -n $NS. You should see an output like the following:

     $ kubectl get pods -n $NS
 NAME                        READY   STATUS    RESTARTS       AGE
 lucenia-cluster-manager-0   2/2     Running   0              8d
 lucenia-cluster-manager-1   2/2     Running   0              8d
 lucenia-cluster-manager-2   2/2     Running   0              8d

  5. Exec into one of the lucenia cluster manager pods:

     kubectl exec -it lucenia-cluster-manager-0 -n $NS -- /bin/bash

  6. Query the Lucenia REST API to verify that the service is running. You should use -k (also written as --insecure) to disable hostname checking because the default security configuration uses demo certificates. Use -u to pass the default username and password (admin:<custom-admin-password>):

     curl https://localhost:9200 -ku admin:<custom-admin-password>

    The response confirms that the installation was successful:

     {
     "name" : "lucenia-cluster-manager-1",
     "cluster_name" : "lucenia-cluster",
     "cluster_uuid" : "X3PKKnWu9QKGFWd0vJTlRrA",
     "version" : {
         "distribution" : "skylite",
         "number" : "0.1.0",
         "build_type" : "tar",
         "build_hash" : "4044f30b37cfc31ea2b2789e0248fdd40cfbde23",
         "build_date" : "2024-07-26T15:50:14.800302765Z",
         "build_snapshot" : false,
         "lucene_version" : "9.11.0",
         "minimum_wire_compatibility_version" : "2.14.0",
         "minimum_index_compatibility_version" : "2.0.0"
     },
     "tagline" : "[Search]...on your terms"
 }

Further reading

You successfully deployed your own Lucenia cluster Now you’re ready to learn about configuration and functionality in more detail. Here are a few recommendations on where to begin:

Other installation types

In addition to Docker, you can install Lucenia on various Linux distributions and on Windows. For all available installation guides, see Install and upgrade Lucenia.

Next steps

Installation Quickstart References

Create Self-Signed Certificates

This section walks through creating self-signed certificates using openssl.

The following steps are a guide to creating self-signed certificates:

  1. Create a private key. This must be kept secure.
  2. Create a self-signed certificate for the root CA using the private key.
  3. Create an admin certificate: create a private key, convert the key to PKCS8 format, create a certificate signing request (CSR), and create the admin certificate.
    • When creating the CSR, follow the prompts to fill in the required information. If hostname verification is enabled, the Common Name (CN) must match the DNS A record. If you know the subject information, it can be provided with the -subj flag; the script has variables for the subject information which should be updated.
  4. Create node and client certificates (optional).
    • Each certificate should be created with its own private key and CSR; additionally, the node and client certificates should be generated with a SAN (Subject Alternative Name) extension matching the DNS A record.

A script is provided to assist in this process, and can be modified to fit your needs. The script generates certificates for the root CA, admin, node(s), and client. The expiration is set for 365 days; update the expiration as needed. The script also includes variables for the subject and SAN information which should be updated.

#!/bin/bash

# This script generates certificates for the root CA, admin, node(s), and client.
# The expiration is set for 365 days. Update the expiration as needed.

# Create a list of nodes. Update the name of nodes, add/remove nodes as needed.
declare -a nodes=("mynode") # Or for multiple, `declare -a nodes=("node-0" "node-1" "node-2")`

# Define subj for each certificate
# Update the values of the subj variables as needed.
# NOTE: The node_subj variable is updated for each node in the for loop. Update the static
# values of the node_subj variable as needed.
root_ca_subj="/C=US/ST=CA/O=Example/CN=root-ca.dns.a-record"
admin_subj="/C=US/ST=CA/O=Example/CN=admin.dns.a-record"
client_subj="/C=US/ST=CA/O=Example/CN=client.dns.a-record"

# Define the subjectAltName
# Update the values of the san variables as needed.
# NOTE: The node_san variable is updated for each node in the for loop.
client_san="subjectAltName=DNS:client.dns.a-record"

# Root CA
openssl genrsa -out root-ca-key.pem 2048
openssl req -new -x509 -sha256 -key root-ca-key.pem -subj "$root_ca_subj" -out root-ca.pem -days 365

# Admin cert
openssl genrsa -out admin-key-temp.pem 2048
openssl pkcs8 -inform PEM -outform PEM -in admin-key-temp.pem -topk8 -nocrypt -v1 PBE-SHA1-3DES -out admin-key.pem
openssl req -new -key admin-key.pem -subj "$admin_subj" -out admin.csr
openssl x509 -req -in admin.csr -CA root-ca.pem -CAkey root-ca-key.pem -CAcreateserial -sha256 -out admin.pem -days 365

# Node certs
for node in "${nodes[@]}";
do

    node_subj="/C=US/ST=CA/O=Example/CN=$node.dns.a-record"
    node_san="subjectAltName=DNS:$node.dns.a-record"

    openssl genrsa -out "$node"-key-temp.pem 2048

    openssl pkcs8 -inform PEM -outform PEM -in "$node"-key-temp.pem -topk8 -nocrypt -v1 PBE-SHA1-3DES -out "$node"-key.pem

    openssl req -new -key "$node"-key.pem -subj "$node_subj" -out "$node".csr

    echo "$node_san" > "$node".ext

    openssl x509 -req -in "$node".csr -CA root-ca.pem -CAkey root-ca-key.pem -CAcreateserial -sha256 -out "$node".pem -days 365 -extfile "$node".ext

done

# Client cert
openssl genrsa -out client-key-temp.pem 2048
openssl pkcs8 -inform PEM -outform PEM -in client-key-temp.pem -topk8 -nocrypt -v1 PBE-SHA1-3DES -out client-key.pem
openssl req -new -key client-key.pem -subj "$client_subj" -out client.csr
echo "$client_san" > client.ext
openssl x509 -req -in client.csr -CA root-ca.pem -CAkey root-ca-key.pem -CAcreateserial -sha256 -out client.pem -days 365 -extfile client.ext
350 characters left

Have a question? .