Skip to content

elasticsearch-deployment-quickstart.md

Latest commit

 

History

History
192 lines (133 loc) · 8.82 KB

elasticsearch-deployment-quickstart.md

File metadata and controls

192 lines (133 loc) · 8.82 KB
Raw
navigation_title Deploy an {{es}} cluster
mapped_pages
applies_to
deployment
eck
all
products
id
cloud-kubernetes

Deploy an {{es}} cluster [k8s-deploy-elasticsearch]

To deploy a simple {{es}} cluster specification, with one {{es}} node:

cat <<EOF | kubectl apply -f -
apiVersion: elasticsearch.k8s.elastic.co/v1
kind: Elasticsearch
metadata:
  name: quickstart
spec:
  version: {{version.stack}}
  nodeSets:
  - name: default
    count: 1
    config:
      node.store.allow_mmap: false
EOF

The operator automatically creates and manages Kubernetes resources to achieve the desired state of the {{es}} cluster. It may take up to a few minutes until all the resources are created and the cluster is ready for use.

::::{warning} Setting node.store.allow_mmap: false has performance implications and should be tuned for production workloads as described in the Virtual memory section. ::::

::::{note} If your Kubernetes cluster does not have any Kubernetes nodes with at least 2GiB of free memory, the pod will be stuck in Pending state. Check Manage compute resources for more information about resource requirements and how to configure them. ::::

::::{note} The cluster that you deployed in this quickstart guide only allocates a persistent volume of 1GiB for storage using the default storage class defined for the Kubernetes cluster. You will most likely want to have more control over this for production workloads. Refer to Volume claim templates for more information. ::::

For a full description of each CustomResourceDefinition (CRD), refer to the API Reference or view the CRD files in the [project repository](https://github.com/elastic/cloud-on-k8s/tree/{{version.eck | M.M}}/config/crds). You can also retrieve information about a CRD from the cluster. For example, describe the {{es}} CRD specification with describe:

kubectl describe crd elasticsearch

Monitor cluster health and creation progress [k8s-elasticsearch-monitor-cluster-health]

Get an overview of the current {{es}} clusters in the Kubernetes cluster with get, including health, version and number of nodes:

kubectl get elasticsearch

When you first create the Kubernetes cluster, there is no HEALTH status and the PHASE is empty. After the pod and service start-up, the PHASE turns into Ready, and HEALTH becomes green. The HEALTH status comes from {{es}}'s cluster health API.

NAME          HEALTH    NODES     VERSION   PHASE         AGE
quickstart              1         {{version.stack}}               1s

While the {{es}} pod is in the process of being started it will report Pending as checked with get:

kubectl get pods --selector='elasticsearch.k8s.elastic.co/cluster-name=quickstart'

Which will output similar to:

NAME                      READY   STATUS    RESTARTS   AGE
quickstart-es-default-0   0/1     Pending   0          9s

During and after start-up, up that pod’s logs can be accessed:

kubectl logs -f quickstart-es-default-0

Once the pod has finished coming up, our original get request will now report:

NAME          HEALTH    NODES     VERSION   PHASE         AGE
quickstart    green     1         {{version.stack}}     Ready         1m

Access your {{es}} cluster [k8s_request_es_access]

ECK automatically creates a ClusterIP service for HTTP access to your cluster. You can verify it with kubectl get:

kubectl get service quickstart-es-http

Which will output similar to:

NAME                 TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
quickstart-es-http   ClusterIP   10.15.251.145   <none>        9200/TCP   34m

In order to make requests to the {{es}} API:

  1. Get the credentials.

    By default, a user named elastic is created with the password stored inside a Kubernetes secret. This default user can be disabled if desired, refer to Users and roles for more information.

    PASSWORD=$(kubectl get secret quickstart-es-elastic-user -o go-template='{{.data.elastic | base64decode}}')

  2. Retrieve the CA certificate.

    By default, ECK enables HTTPS for {{es}}, generates a private CA for each cluster, and issues certificates signed for the associated DNS service names, such as quickstart-es-http.<namespace>.svc.

    The CA certificate is available in the <name>-es-http-certs-public secret. For this quickstart cluster, run the following command to save the CA certificate to a local file named quickstart-es-ca.crt:

    kubectl get secret quickstart-es-http-certs-public -o go-template='{{index .data "ca.crt" | base64decode }}' > quickstart-es-ca.crt

    Refer to Manage HTTP certificates on ECK for information about customizing HTTP TLS configuration.

  3. Issue a request to the {{es}} info API. You can do so from inside the {{k8s}} cluster or from your local workstation.

    :::{tip} The following examples use curl to access the {{es}} endpoint with full TLS verification, providing the CA certificate with the --cacert option.

    For testing only, you can use --insecure (or -k) to skip certificate verification. This flag turns off TLS trust checks and should not be used in production. :::

    • From inside the Kubernetes cluster

      Use the service name to access the {{es}} endpoint from any {{k8s}} Pod:

      curl --cacert <PATH_TO_CA> -u "elastic:$PASSWORD" "https://quickstart-es-http.<namespace>.svc:9200" <1>
      1. Replace <namespace> with the namespace where your {{es}} cluster is deployed.

      For example, if you run the command from an {{es}} Pod and the cluster is deployed in the default namespace, you can run:

      curl --cacert /usr/share/elasticsearch/config/http-certs/ca.crt \
  -u "elastic:$PASSWORD" "https://quickstart-es-http.default.svc:9200"

    • From your local workstation

      1. Start a local port-forward in a separate terminal to route localhost:9200 to the quickstart-es-http {{k8s}} Service:

        kubectl port-forward service/quickstart-es-http 9200

        :::{note} Port-forwarding is mainly intended for local testing. In production environments, if the cluster must be accessible from outside the {{k8s}} cluster, consider using a LoadBalancer service or another exposure mechanism. Refer to Allow public access for more information. :::

      2. Access {{es}} through the forwarded port:

        curl --cacert quickstart-es-ca.crt -u "elastic:$PASSWORD" "https://localhost:9200"

        The previous command validates the certificate with the provided CA, but hostname verification fails because localhost is not present in the certificate SANs. To perform full TLS verification of both the certificate and the requested hostname, use:

        NAMESPACE=default <1>
curl --cacert quickstart-es-ca.crt -u "elastic:$PASSWORD" \
  --resolve quickstart-es-http.${NAMESPACE}.svc:9200:127.0.0.1 \
  "https://quickstart-es-http.${NAMESPACE}.svc:9200"
        1. Set NAMESPACE to the namespace where your {{es}} cluster is deployed.

Next steps

This completes the quickstart of deploying an {{es}} cluster. We recommend continuing to: