Docs Developer Site
DeveloperDocsKubernetes Operator For XpStableInstallation

Installation

Contents

This section covers the installation of the Enonic XP Kubernetes Operator.

Prerequisites

Kubernetes

A running Kubernetes cluster version 1.22+. The k8s cluster can be on-premise or any cloud service provider. The only thing that differs depending on the type of k8s clusters is which storage class to use. And more information about that is shown in the "Storage classes" section below.

Kubectl

Is the Kubernetes command-line tool, kubectl, allows you to run commands against Kubernetes clusters. Download it here.

Helm

Is a package manager for Kubernetes. Download it here.

Namespaces

This guide instructs you to install the operator (and potentially the NFS provisioner) into the kube-system namespace. Although this is not a strict requirement, it is best practice to install kubernetes extensions into a namespace that clearly indicates that it has components vital to the system. Since kube-system is present in all clusters and should never be deleted, it is recommended to use that. You can create your own my-system namespace and install the operator there. Do not, for example, install the operator and an XP7 deployment into the same namespace.

Storage classes

Before we deploy the operator, we need to talk about storage classes. That should be a familiar concept to people that have worked on kubernetes clusters before. If you do not know what they are, you can basically think of them as different approaches to store your data. Each storage class can create volumes that have one of these four access modes:

  • ReadWriteOnce: Can be mounted as read-write by a single node. Multiple pods can access the volume when the pods are running on the same node.

  • ReadOnlyMany: Can be mounted read-only by many nodes.

  • ReadWriteMany: Can be mounted as read-write by many nodes.

  • ReadWriteOncePod: Can be mounted as read-write by a single pod.

ReadWriteOnce mode is supported by the default storage classes in any k8s cluster; that satisfies the requirement of XP deployment in single mode. However, to deploy XP in cluster mode, an NFS based storage class with "ReadWriteMany" access mode is required.

For instance, the standard storage class in minikube supports all modes and can be used to deploy XP in single as well as in cluster mode. However, the standard storage classes in the major managed k8s providers like GKE, AKS and EKS do not support ReadWriteMany mode. Most storage classes that support ReadWriteMany access mode have also a restriction in changing the modified time of files that XP requires. At the time of this writing, the only storage classes that can be used to deploy XP in cluster mode are NFS based storage classes with ReadWriteMany access mode. Refer to the table below to see which storage class you can use on the major cloud service providers.

Compatible Storage classes for running XP in single and cluster mode

XP deployment mode Google Azure Amazon

Single

Any storage class with RWO

Any storage class with RWO

Any storage class with RWO

Cluster

Filestore CSI driver based storage class with RWM*

Azurefile CSI driver based storage class with RWM*

EFS

* NFS based CSI driver storage classes in AKS and GKE have minimum size requirements which can be very high depending on your storage requirement. Please refer to the respective cloud provider’s site for more information.

Note: In GKE and AKS, you can get managed storage classes that are NFS based CSI driver storage backends. However, for Amazon EKS you need to create the ´EFS´ storage class. See our EFS storage class guide for more information.

Provisioning NFS based storage class

If you are running an ´on-premiser´ k8s cluster or you don’t want to use the available NFS based storage classes in managed k8s clusters, you have the possibility to self provision NFS based storage classes. See our NFS storage class guide for more information.

Installation

Create chart values file

The chart values.yaml file is how you generally configure a deployment with Helm (to learn more about how Helm uses values files, visit the Helm developer docs). You can read more about available values you can configure for the operator in the Helm chart readme. Lets create a Helm values file to configure the operator:

Here you might have to change the storage classes depending on your cluster setup.
values.yaml 
config: |-
  # Set storage classes for XP deployments. Note that these two do not have to be the same.
  # The shared storage class has to support ReadWriteMany!
  operator.charts.values.storage.shared.storageClassName=nfs
  operator.charts.values.storage.default.storageClassName=standard

  # Lower default requests: This is useful when trying out XP clusters when
  #   the K8s cluster does not have enough memory and ram!
  operator.charts.values.resources.cpu.defaultRequests=0.2
  operator.charts.values.resources.memory.defaultRequests=512Mi

Installing chart

$ helm upgrade --install \
	--namespace kube-system \
	--values values.yaml \
	xp-operator \
	https://repo.enonic.com/helm/xp-operator/xp-operator-0.17.16.tgz

Release "xp-operator" does not exist. Installing it now.
NAME: xp-operator
LAST DEPLOYED: Wed Apr 27 17:18:38 2022
NAMESPACE: kube-system
STATUS: deployed
REVISION: 1
TEST SUITE: None

Verify installation

First find out the name of the operator pod:

$ kubectl -n kube-system get pods

NAME                                        READY   STATUS              RESTARTS   AGE
coredns-6955765f44-ksgmf                    1/1     Running             0          6m36s
xp-operator-5869fcf9f4-xrzll                0/1     ContainerCreating   0          10s
etcd-minikube                               1/1     Running             0          6m30s
ingress-nginx-admission-create-zl98b        0/1     Completed           0          6m21s
ingress-nginx-admission-patch-7xqtf         0/1     Completed           2          6m20s
ingress-nginx-controller-7f9bbb757f-nxqz6   1/1     Running             0          6m21s
kube-apiserver-minikube                     1/1     Running             0          6m30s
kube-controller-manager-minikube            1/1     Running             0          6m30s
kube-proxy-f4v7v                            1/1     Running             0          6m36s
kube-scheduler-minikube                     1/1     Running             0          6m30s
nfs-server-nfs-server-provisioner-0         1/1     Running             0          3m40s
storage-provisioner                         1/1     Running             0          6m50s

Then look at the operator logs to see if there are any errors:

$ kubectl -n kube-system logs -f xp-operator-5869fcf9f4-xrzll

exec java -Doperator.charts.path=helm -Djava.util.logging.manager=org.jboss.logmanager.LogManager -javaagent:/opt/agent-bond/agent-bond.jar=jmx_exporter{{9779:/opt/agent-bond/jmx_exporter_config.yml}} -XX:+ExitOnOutOfMemoryError -cp . -jar /deployments/quarkus-run.jar
__  ____  __  _____   ___  __ ____  ______
 --/ __ \/ / / / _ | / _ \/ //_/ / / / __/
 -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
--\___\_\____/_/ |_/_/|_/_/|_|\____/___/
2022-04-27 15:18:45,068 INFO  io.quarkus - operator 0.17.13 on JVM (powered by Quarkus 2.8.1.Final) started in 1.572s. Listening on: https://0.0.0.0:8443
2022-04-27 15:18:45,070 INFO  io.quarkus - Profile prod activated.
2022-04-27 15:18:45,070 INFO  io.quarkus - Installed features: [cdi, kubernetes-client, micrometer, rest-client, resteasy, resteasy-jackson, smallrye-context-propagation, vertx]
2022-04-27 15:18:48,480 INFO  com.eno.kub.ope.Operator - Adding listener 'OperatorXp7AppInstaller'
2022-04-27 15:18:48,481 INFO  com.eno.kub.ope.Operator - Adding schedule 'OperatorXp7AppStatus' [delay: 19241, period: 60000]
2022-04-27 15:18:48,481 INFO  com.eno.kub.ope.Operator - Adding schedule 'OperatorXp7AppInstaller' [delay: 4497, period: 60000]
2022-04-27 15:18:48,480 INFO  com.eno.kub.ope.Operator - Adding listener 'OperatorIngressCertSync'
2022-04-27 15:18:48,484 INFO  com.eno.kub.ope.Operator - Adding listener 'OperatorXp7DeploymentStatus'
2022-04-27 15:18:48,484 INFO  com.eno.kub.ope.Operator - Adding schedule 'OperatorXp7DeploymentStatus' [delay: 6627, period: 60000]
2022-04-27 15:18:48,485 INFO  com.eno.kub.ope.Operator - Adding listener 'OperatorXpClientCacheInvalidate'
2022-04-27 15:18:48,488 INFO  com.eno.kub.ope.Operator - Adding listener 'OperatorXp7AppStatusOnDeployments'
2022-04-27 15:18:48,488 INFO  com.eno.kub.ope.Operator - Adding listener 'OperatorIngress'
2022-04-27 15:18:48,488 INFO  com.eno.kub.ope.Operator - Adding schedule 'OperatorXp7ConfigSync' [delay: 13876, period: 60000]
2022-04-27 15:18:48,488 INFO  com.eno.kub.ope.Operator - Adding listener 'OperatorDomainCertSync'
2022-04-27 15:18:48,727 INFO  com.eno.kub.ope.Operator - Adding listener 'OperatorXp7DeploymentHelm'
2022-04-27 15:18:48,727 INFO  com.eno.kub.ope.Operator - Adding listener 'OperatorXp7AppStartStopper'
2022-04-27 15:18:48,728 INFO  com.eno.kub.ope.Operator - Adding schedule 'OperatorXp7AppStartStopper' [delay: 4061, period: 60000]
2022-04-27 15:18:48,728 INFO  com.eno.kub.ope.Operator - Adding listener 'OperatorXp7ConfigStatus'
2022-04-27 15:18:48,728 INFO  com.eno.kub.ope.Operator - Adding listener 'OperatorIngressLabel'
2022-04-27 15:18:48,729 INFO  com.eno.kub.ope.Operator - Adding schedule 'OperatorIngressLabel' [delay: 3996, period: 60000]
2022-04-27 15:18:48,729 INFO  com.eno.kub.ope.Operator - Adding schedule 'OperatorInformers' [delay: 10390, period: 30000]
2022-04-27 15:18:48,729 INFO  com.eno.kub.ope.Operator - Adding listener 'OperatorDeleteAnnotation'
2022-04-27 15:18:48,729 INFO  com.eno.kub.ope.Operator - Adding listener 'OperatorConfigMapEvent'
2022-04-27 15:18:48,730 INFO  com.eno.kub.ope.Operator - Adding listener 'OperatorXp7Config'
2022-04-27 15:18:48,730 INFO  com.eno.kub.ope.Operator - Adding schedule 'OperatorConfigMapSync' [delay: 18077, period: 60000]
2022-04-27 15:18:48,831 INFO  com.eno.kub.ope.Operator - Adding listener 'OperatorXp7AppInstallerOnDeployments'
2022-04-27 15:18:53,830 INFO  com.eno.kub.ope.Operator - Starting informers

Contents

Contents