Docs Developer Site
Kubernetes operator for XPInstallation

Installation

Contents

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

Prerequisites

Kubernetes

A running Kubernetes cluster version 1.19+.

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 practices to install kubernetes extentions 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 you own my-system namespace and install the operator there. Do not, for example, install the operator and a 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 managed Kubernetes clusters before. If you do not know what they are, you can basically think of them as different aproaches to store your data (floppy, HDD, SSD, etc). Each storage class can create volumes that have one of these three access modes:

  • ReadWriteOnce: Can be mounted as read-write by a single node

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

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

The reason why we bring this up is because XP, when running in clustered mode, needs shared volumes for some data. If you do not plan on running any XP clusters in your Kubernetes cluster, you are fine and you do not need to worry about storage classes.

However, for XP clusters to work, you need to have a storage class in your cluster that supports creation of ReadWriteMany volumes. For example, the standard storage class in minikube supports all modes, but the standard storage class in GKE does not support ReadWriteMany. Like GKE the standard storage class on Amazon EKS (gp2) does not support ReadWriteMany but you can use Amazon EFS storage class with dynamic provisioning. See our EFS storage class guide for more information. You can find a matrix here that shows you different options.

You can create your own storage class with NFS that supports ReadWriteMany access mode. See our NFS storage class guide for more information. NOTE: The azurefile storageclass on AKS supports RWM access mode, but using that in conjunction with the xp-operator has proven unstable. We recommend usage of NFS on AKS.

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