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: 1.0.4
    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: 1.0.4
    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. Certificates (TLS)

Both Operators are HTTPS (8443) servers that the kube-apiserver connects to. The MutatingWebhookConfiguration and the APIService verify the certificate, so the chart does not install without one.

Value	What it is
`openmaruApmMuatingOperator.caBundle`	The CA certificate that signed the server certificate (PEM, base64)
`openmaruSecret.tlsCrt`	The server certificate (PEM, base64)
`openmaruSecret.tlsKey`	The server private key (PEM, base64)

The certificate SAN must contain both of these. The kube-apiserver connects by these names.

*.openmaru-apm.svc
*.openmaru-apm.svc.cluster.local

Leaving the three values empty makes helm stop while rendering. The chart used to ship a default certificate and its private key, but anyone who received the chart could then impersonate the Operator with that same key, so it was removed.

On OPENMARU COP no extra work is needed. The installer creates the Operator certificate alongside the registry certificate and fills the values in.

On any other Kubernetes installed with Helm directly, use hack/gen-webhook-cert.sh in the chart to create the certificate and a values file. It uses cfssl when available and openssl otherwise; the result is the same.

./hack/gen-webhook-cert.sh ./webhook-certs

helm install openmaru-apm <chart> -n openmaru-apm --create-namespace \\
  -f ./webhook-certs/webhook-cert-values.yaml

The generated webhook-cert-values.yaml and *-key.pem contain a private key. Do not commit them to version control.

To replace the certificate, pass all three values in one helm upgrade and restart the Operators. When caBundle changes, the MutatingWebhookConfiguration and the APIService have to change with it.

helm upgrade openmaru-apm <chart> -n openmaru-apm -f ./webhook-certs/webhook-cert-values.yaml
kubectl -n openmaru-apm rollout restart deploy/openmaru-operator-apm-agent
kubectl -n openmaru-apm rollout restart deploy/openmaru-operator-apm-hpa

Overview​

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

2. Installing with Helm (Without COP)​

3. Checking the Installation​

4. The Key Settings at a Glance​

5. Certificates (TLS)​