2.1. Installation

Overview

This chapter covers how to install OPENMARU APM Operator. An OPENMARU COP environment needs no separate installation; a Kubernetes or OpenShift cluster you built yourself is installed from a Helm chart.

1. OPENMARU COP Environments — Configured Automatically (No Installation)

In an OPENMARU COP (the cloud operations platform, based on Kubernetes/OpenShift) environment this Operator is included in the platform by default and is deployed and configured automatically. COP users therefore do not need to go through the manual or Helm installation below.

• The Operator pods (APM Agent and APM HPA) start together when COP is configured.
• The image registry, the APM server connection details (OMAPM_HOST / OMAPM_PORT), the apmAlias mapping, and the rest of the basic environment are filled in by COP.
• COP users can therefore start straight from 301 Auto-Instrumentation (attaching the label) and 302 Autoscaling.

When a value COP filled in has to change (registering another APM server, for example), adjust the same key in COP's Operator settings as the setting below. What each setting means is in the sections that follow.

The procedure below is for installing manually in an environment that does not use COP (a Kubernetes/OpenShift cluster you built yourself).

2. Installing with Helm (Without COP)

The Operator is installed from the OPENMARU APM Helm chart (the openmaru-apm subchart of openmaru-cop-helm-chart). Agent and HPA are configured under two different keys in values.yaml. Enable the Operator and set the environment under each key as below.

## 1) APM Agent (the auto-instrumentation webhook)
openmaruApmWasAgentOperator:
  enabled: true
  imageAgent:
    repository: registry.openmaru.io/images/openmaru-operator-apm-agent
    # When using the OpenShift internal registry:
    # repository: image-registry.openshift-image-registry.svc.cluster.local:5000/openshift/openmaru-operator-apm-agent
    tag: latest
    pullPolicy: IfNotPresent
  envAgent:
    - name: IMAGE_REGISTRY        # the registry for the khan-agent image to inject
      value: "registry.openmaru.io"
    - name: IMAGE_NAMESPACE       # the namespace within the registry (leading / included)
      value: "/images"
    ## OMAPM_HOST/PORT: the default APM server (a per-Deployment setting wins)
    - name: OMAPM_HOST
      value: "openmaru-apm-server.openmaru-apm.svc.cluster.local"
    - name: OMAPM_PORT
      value: "8080"

## 2) APM HPA (the autoscaling external metric)
openmaruApmHpaOperator:
  enabled: true
  imageHpa:
    repository: registry.openmaru.io/images/openmaru-operator-apm-hpa
    tag: latest
    pullPolicy: IfNotPresent
  ## envHpa — register the APM server address per apmAlias
  ## (the name must match matchLabels.apmAlias in the HPA)
  ## <apmAlias>_ACCESS_KEY gives that APM server's API access key
  envHpa:
    - name: APM-INTERNAL
      value: "http://openmaru-apm-server.openmaru-apm.svc.cluster.local:8080"
    - name: APM-SERVER
      value: "http://192.168.80.190"
    - name: APM-SERVER_ACCESS_KEY
      value: "<APM API access key>"

To use only the Agent or only the HPA, turn off enabled on that key. replicas, strategy, and resources can also be adjusted under each key.

Installation is performed together with the parent COP Helm chart.

helm install openmaru-cop <chart> \
  --namespace openmaru-apm --create-namespace -f values.yaml

3. Checking the Installation

Installing OPENMARU APM/COP together brings up other pods as well -- server, mongo, redis, influx, rabbitmq, sys-agent and the rest. Here we check only the two Operator pods.

The installation is sound when the two Operator pods below are Running (the query is narrowed by label).

kubectl get pod -n openmaru-apm -l 'app in (openmaru-operator-apm-agent,openmaru-operator-apm-hpa)'

NAME                                           READY   STATUS    RESTARTS   AGE
openmaru-operator-apm-agent-xxxxxxxxxx-xxxxx   1/1     Running   0          5m
openmaru-operator-apm-hpa-xxxxxxxxxx-xxxxx     1/1     Running   0          5m

• openmaru-operator-apm-agent : the auto-instrumentation webhook
• openmaru-operator-apm-hpa : the autoscaling metric adapter

4. The Key Settings at a Glance

Setting	Where	Meaning
openmaruApmWasAgentOperator.enabled	top-level key	Whether to install APM Agent (auto-instrumentation)
openmaruApmHpaOperator.enabled	top-level key	Whether to install APM HPA (autoscaling)
imageAgent / imageHpa (repository/tag/pullPolicy)	under each key	The Operator container image
IMAGE_REGISTRY / IMAGE_NAMESPACE	envAgent	Where to fetch the khan-agent image to inject
OMAPM_HOST / OMAPM_PORT	envAgent	The APM server the instrumented target looks at by default (a value set directly on the Deployment wins)
The envHpa entries (APM-*)	envHpa	The apmAlias → APM server URL mapping. <apmAlias>_ACCESS_KEY gives the access key. It decides which server the HPA queries

With several APM servers, register each under a different name (= apmAlias) in envHpa and pick between them with matchLabels.apmAlias in the HPA. For details see 302 Autoscaling.

5. A Note on Certificates (TLS)

APM HPA runs as a Kubernetes API extension, so it needs HTTPS (8443) and a certificate. The Helm chart includes a default certificate, so no extra work is normally needed. If the certificate has to be replaced (expiry, a domain change, and so on), see the "keystore / caBundle generation" section of the repository root README.md.

---