Installation

Prerequisites

Before you can install the operator, you must have a running k8s cluster + Kubectl and Helm installed on your local machine. See details below.

We recommend using the latest version of Kubernetes. The minimal version of Kubernetes required by XP Operator is 1.27+.

Kubernetes: The k8s cluster can be hosted by any cloud service provider, or even run on premises. The only thing that differs is which storage classes you can use.

Follow these steps to create a managed cluster using Amazon Web Services (AWS), Google Cloud Platform GCP, or Microsoft Azure.
Kubectl: Is the Kubernetes command-line tool, kubectl, allows you to run commands against Kubernetes clusters. Download it from kubernetes.io.
Helm: Is a package manager for Kubernetes. Download it from helm.sh.

Create chart values file

With the prerequisites in place, you can start setting up your Helm chart file. This is used to configure the XP operator.

Create a chart file in a suitable location on your computer:

values.yaml

config: |-
  # Set storage class names for volumes to be used by XP deployments.
  operator.charts.values.storage.default.storageClassName=standard
  operator.charts.values.storage.shared.storageClassName=nfs

  # Minimum CPU and RAM to be requested by XP deployments
  operator.charts.values.resources.cpu.defaultRequests=1
  operator.charts.values.resources.memory.defaultRequests=2Gi

Default storage: For ideal performance, use an SSD backed storage class

Shared storage: Must be an NFS compatible storage class available in your cluster

Visit the storage classes section for more details and compatibility list of supported storage classes.

The complete list of operator configuration options can be found in the Operator Helm chart

Installing the operator

Run the following command to install the operator on your cluster:

Namespaces - We will be installing the XP operator in the default kube-system namespace, indicating that it is a vital system component, but you can also create your own if desired.

$ helm upgrade --install \
	--namespace kube-system \
	--values values.yaml \
	xp-operator \
	<URL to operator i.e. https://repo.enonic.com/repository/helm/xp-operator-1.0.0.tgz>

Availablle operator versions: https://repo.enonic.com/#browse/browse:helm:xp-operator

The result should look something like this:

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

Find the name of the operator pod. The name of the pod will start with xp-operator:

$ kubectl -n kube-system get pods

NAME                                                                READY   STATUS              RESTARTS   AGE
pod/event-exporter-gke-7bf6c99dcb-7dl56                             2/2     Running             0          16d
pod/kube-dns-5bfd847c64-2562d                                       4/4     Running             0          16d
pod/kube-proxy-gke-xp-test-gke-cluster-default-pool-d0fdd01c-jnfl   1/1     Running             0          16d
pod/l7-default-backend-d86c96845-j6m9b                              1/1     Running             0          16d
pod/xp-operator-684bb48cc5-bqjqc                                    0/1     ContainerCreating   0          9s

Check the operator logs for errors. Logs for a working operator should look something like this:

$ kubectl -n kube-system logs -f xp-operator-684bb48cc5-bqjqc

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
__  ____  __  _____   ___  __ ____  ______
 --/ __ \/ / / / _ | / _ \/ //_/ / / / __/
 -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
--\___\_\____/_/ |_/_/|_/_/|_|\____/___/
2024-01-02 23:12:24,760 INFO  io.quarkus - java-operator 0.22.1 on JVM (powered by Quarkus 2.16.6.Final) started in 6.579s. Listening on: https://0.0.0.0:8443
2024-01-02 23:12:24,762 INFO  io.quarkus - Profile prod activated.
2024-01-02 23:12:24,764 INFO  io.quarkus - Installed features: [cdi, micrometer, rest-client, resteasy, resteasy-jackson, smallrye-context-propagation, vertx]
2024-01-02 23:12:25,808 INFO  com.eno.kub.ope.Operator - Adding listener 'OperatorIngress'
2024-01-02 23:12:25,889 INFO  com.eno.kub.ope.Operator - Adding listener 'OperatorXpClientCacheInvalidate'
2024-01-02 23:12:27,738 INFO  com.eno.kub.ope.Operator - Adding listener 'OperatorXp7DeploymentHelm'
2024-01-02 23:12:27,787 INFO  com.eno.kub.ope.Operator - Adding listener 'OperatorXp7AppStatusOnDeployments'
2024-01-02 23:12:27,799 INFO  com.eno.kub.ope.Operator - Adding listener 'OperatorDeleteAnnotation'
2024-01-02 23:12:27,803 INFO  com.eno.kub.ope.Operator - Adding schedule 'OperatorInformers' [delay: 16337, period: 30000]
2024-01-02 23:12:27,803 INFO  com.eno.kub.ope.Operator - Adding listener 'OperatorXp7ConfigStatus'
2024-01-02 23:12:27,804 INFO  com.eno.kub.ope.Operator - Adding listener 'OperatorIngressLabel'
2024-01-02 23:12:27,804 INFO  com.eno.kub.ope.Operator - Adding listener 'OperatorXp7AppInstaller'
2024-01-02 23:12:27,805 INFO  com.eno.kub.ope.Operator - Adding schedule 'OperatorXp7AppInstaller' [delay: 15212, period: 60000]
2024-01-02 23:12:27,805 INFO  com.eno.kub.ope.Operator - Adding listener 'OperatorXp7AppInstallerOnDeployments'
2024-01-02 23:12:27,806 INFO  com.eno.kub.ope.Operator - Adding listener 'OperatorConfigMapEvent'
2024-01-02 23:12:27,803 INFO  com.eno.kub.ope.Operator - Adding schedule 'OperatorConfigMapSync' [delay: 13252, period: 60000]
2024-01-02 23:12:27,804 INFO  com.eno.kub.ope.Operator - Adding schedule 'OperatorIngressLabel' [delay: 6622, period: 60000]
2024-01-02 23:12:27,806 INFO  com.eno.kub.ope.Operator - Adding listener 'OperatorXp7Config'
2024-01-02 23:12:27,807 INFO  com.eno.kub.ope.Operator - Adding listener 'OperatorIngressCertSync'
2024-01-02 23:12:27,807 INFO  com.eno.kub.ope.Operator - Adding schedule 'OperatorXp7ConfigSync' [delay: 10124, period: 60000]
2024-01-02 23:12:27,808 INFO  com.eno.kub.ope.Operator - Adding listener 'OperatorDomainCertSync'
2024-01-02 23:12:27,809 INFO  com.eno.kub.ope.Operator - Adding listener 'OperatorXp7AppStartStopper'
2024-01-02 23:12:27,809 INFO  com.eno.kub.ope.Operator - Adding schedule 'OperatorXp7AppStartStopper' [delay: 14806, period: 60000]
2024-01-02 23:12:27,809 INFO  com.eno.kub.ope.Operator - Adding listener 'OperatorXp7DeploymentStatus'
2024-01-02 23:12:27,810 INFO  com.eno.kub.ope.Operator - Adding schedule 'OperatorXp7DeploymentStatus' [delay: 4146, period: 60000]
2024-01-02 23:12:27,810 INFO  com.eno.kub.ope.Operator - Adding schedule 'OperatorXp7AppStatus' [delay: 19524, period: 60000]
2024-01-02 23:12:32,807 INFO  com.eno.kub.ope.Operator - Starting informers

The best way of verifying that things are working, is by creating a basic xp7deployment. The example below will create a namespace, a single-node XP7 server, pre-install selected applications, and configure an ingress.

Remember to use a unique namespace per XP deployment. Never use the same namespace as the operator.

Create xp7deployment

Place this yaml file in a suitable location on your computer:

Make sure the spec is updated with latest versions of XP and other softwarwe listed.

simple.yaml

# Create a namespace
apiVersion: v1
kind: Namespace
metadata:
  name: my-namespace
  annotations:
    # Delete this namespace if the deployment is deleted
    enonic.cloud/remove.with.xp7deployment: my-deployment
---
# Create deployment in the namespace
apiVersion: enonic.cloud/v1
kind: Xp7Deployment
metadata:
  name: my-deployment
  namespace: my-namespace
spec:
  enabled: true
  xpVersion: 7.14.4

  # Create one node
  nodeGroups:
    - name: main
      replicas: 1

      data: true
      master: true

      initContainers:
        # Preinstall Snapshotter app
        - image: enonic/snapshotter:3.2.1
          name: snapshotter-deploy
          mounts:
            - name: deploy
              mountPath: /deploy

      resources:
        # Max limits for CPU and Memory
        cpu: "2"
        memory: 8Gi
        dirs:
          # Snapshotter app copied to deploy folder
          - name: deploy
            size: 100Mi
            mountReadOnly: true
        # Disks private to the node
        disks:
          - name: blobstore
            size: 1Gi
          - name: snapshots
            size: 1Gi
          - name: export # Dumps and other data
            size: 1Gi
          - name: index # Node ES index
            size: 1Gi
          - name: work # Node cache
            size: 1Gi
---
# Install content studio
apiVersion: enonic.cloud/v1
kind: Xp7App
metadata:
  name: contentstudio
  namespace: my-namespace
spec:
  url: https://repo.enonic.com/public/com/enonic/app/contentstudio/5.2.3/contentstudio-5.2.3.jar
  sha512: 70499d8612a4c0b4f12dc7c5dfe171b4ad331cf8df48af94de1a92b8fc8ab935916bb798f646cb7a358b5a0e1b2d9a2c1509671566d76dcea3d03f7142d4ba83
---
# Add your own custom config
apiVersion: enonic.cloud/v1
kind: Xp7Config
metadata:
  name: my-config
  namespace: my-namespace
spec:
  nodeGroup: all
  file: com.my-app.cfg
  data: |
    my = config
---
# Expose XP through an ingress
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-domain-com
  namespace: my-namespace
  annotations:
    enonic.cloud/xp7.vhost.mapping.my-mapping-site.source: /
    enonic.cloud/xp7.vhost.mapping.my-mapping-site.target: /site/default/master/homepage

    enonic.cloud/xp7.vhost.mapping.my-mapping-admin.source: /admin
    enonic.cloud/xp7.vhost.mapping.my-mapping-admin.target: /admin
    enonic.cloud/xp7.vhost.mapping.my-mapping-admin.idproviders: system
spec:
  rules:
    - host: my-domain.com
      http:
        paths:
          - path: /
            pathType: ImplementationSpecific
            backend:
              service:
                name: main
                port:
                  number: 8080

          - path: /admin
            pathType: ImplementationSpecific
            backend:
              service:
                name: main
                port:
                  number: 8080

Then run the following command to create the xp7deployment:

kubectl apply -f simple.yaml

Output from a successful command

namespace/my-namespace created
xp7deployment.enonic.cloud/my-deployment created
xp7app.enonic.cloud/contentstudio created
xp7config.enonic.cloud/my-config created
ingress.networking.k8s.io/my-domain-com created

Verify that the namespace exists, and that the pods have started:

kubectl -n my-namespace get pods

Access XP Admin

With the XP running, we can try accessing the Admin - even without using an ingress.

Get the su password by running this command:

$ kubectl -n my-namespace get secret su -o go-template="{{ .data.pass | base64decode }}"

This will output the plain text password.

Activate port forwarding

$ kubectl -n my-namespace port-forward main-0 8080

Forwarding from 127.0.0.1:8080 -> 8080
Forwarding from [::1]:8080 -> 8080

Open http://localhost:8080 in your browser, and login with su and the password you obtained earlier.

Visit the operator usage section for more details.

Remove deployment

To remove the test deployment, run the following command:

Use the same yaml as when creating the deployment

kubectl delete -f simple.yaml

Volumes are typically not deleted when you remove the deployment, so take care to remove them afterwards.

Uninstalling the operator

Don´t uninstall the xp-operator while there are remaining xp7Deployments on your cluster

To remove the XP operator from your Kubernetes cluster, run the following command:

helm uninstall xp-operator

Installation

Contents

Prerequisites

Create chart values file

Installing the operator

Verify installation

Test the operator

Create xp7deployment

Access XP Admin

Remove deployment

Uninstalling the operator

Contents

Contents