Deploy OneAgent on Kubernetes

For full-stack monitoring of Kubernetes clusters, you need to roll-out OneAgent on each cluster node using OneAgent Operator for Kubernetes 1.9 or higher. For Kubernetes 1.8 or lower, you need to deploy a DaemonSet.

Note:
For the following distributions of Kubernetes, please refer to the dedicated instructions:

OneAgent Operator for Kubernetes 1.9 or higher DaemonSet for Kubernetes 1.8 or lower

Prepare DESK tokens for OneAgent Operator

Note:
OneAgent Operator v0.3+ requires Kubernetes v1.11 or higher. Older versions of the OneAgent Operator work with Kubernetes v1.9 or higher.

OneAgent Operator requires two different tokens for interacting with DESK servers. These two tokens are made available to OneAgent Operator by means of a Kubernetes secret as explained at a later step.

Get an API token for the DESK API with the scope Access problem and event feed, metrics, and topology. This token is later referenced as API_TOKEN.
Get a Platform-as-a-Service token. This token is later referenced as PAAS_TOKEN.
How to get your PaaS token
1. Login with your DESK account.
2. Select Deploy DESK from the navigation menu.
3. Click the Set up PaaS integration button.
4. Your environment ID appears in the Environment ID text box. You'll need this ID to link your DESK account with your PaaS environment. Click Copy to copy the ID to the clipboard. You can do this at any time by revisiting this page.
5. To generate a PaaS token, click the Generate new token button. The PaaS token is essentially an API token that's used in combination with your environment ID to download DESK OneAgent. As you'll see, there's also a default InstallerDownload token available that you can alternatively use. However, for security reasons, it's recommended that you create several discrete tokens for each environment you have.
6. Type in a meaningful name for your PaaS token. A meaningful token name might be the name of the PaaS platform you want to monitor (for example, azure, cloud-foundry, or openshift). To view and manage your existing PaaS tokens, go to Settings -> Integration -> Platform as a Service.
7. Click Generate to create the PaaS token. The newly created PaaS token will appear in the list below. Click Copy to copy the generated token to the clipboard. You can do this at any time by revisiting this page and clicking Show token next to the relevant PaaS token.

Install OneAgent Operator

Create the necessary objects for OneAgent Operator. OneAgent Operator acts on its separate namespace desk. It holds the operator deployment and all dependent objects like permissions, custom resources and the corresponding DaemonSet. You can also observe the logs of OneAgent Operator.

$ kubectl create namespace desk
$ LATEST_RELEASE=$(curl -s https://api.github.com/repos/desk/desk-oneagent-operator/releases/latest | grep tag_name | cut -d '"' -f 4)
$ kubectl create -f https://raw.githubusercontent.com/DESK/desk-oneagent-operator/$LATEST_RELEASE/deploy/kubernetes.yaml
$ kubectl -n desk logs -f deployment/desk-oneagent-operator

Create the secret holding API and PaaS tokens for authenticating to the DESK cluster. The name of the secret is important in a later step when you configure the custom resource (.spec.tokens). In the following code-snippet the name is oneagent. Be sure to replace API_TOKEN and PAAS_TOKEN with the values explained above.

$ kubectl -n desk create secret generic oneagent --from-literal="apiToken=API_TOKEN" --from-literal="paasToken=PAAS_TOKEN"

Save the following custom resource snippet to a file cr.yaml. The rollout of DESK OneAgent is governed by a custom resource of type OneAgent.

Custom resource snippet

Download

apiVersion: desk.com/v1alpha1
kind: OneAgent
metadata:
  # a descriptive name for this object.
  # all created child objects will be based on it.
  name: oneagent
  namespace: desk
spec:
  # desk api url including `/api` path at the end
  apiUrl: https://ENVIRONMENTID.live.desk.com/api
  # disable certificate validation checks for installer download and API communication
  skipCertCheck: false
  # name of secret holding `apiToken` and `paasToken`
  # if unset, name of custom resource is used
  tokens: ""
  # node selector to control the selection of nodes (optional)
  nodeSelector: {}
  # https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/ (optional)
  tolerations:
  - effect: NoSchedule
    key: node-role.kubernetes.io/master
    operator: Exists
  # oneagent installer image (optional)
  # certified image from Red Hat Container Catalog for use on OpenShift: registry.connect.redhat.com/desk/oneagent
  # defaults to docker.io/desk/oneagent
  image: ""
  # arguments to oneagent installer (optional)
  # https://www.desk.com/support/help/shortlink/oneagent-docker#limitations
  args:
  - APP_LOG_CONTENT_ACCESS=1
  # environment variables for oneagent (optional)
  env: []
  # resource settings for oneagent pods (optional)
  # consumption of oneagent heavily depends on the workload to monitor
  # please adjust values accordingly
  #resources:
  #  requests:
  #    cpu: 200m
  #    memory: 1Gi
  #  limits:
  #    cpu: 600m
  #    memory: 3Gi
  # priority class to assign to oneagent pods (optional)
  # https://kubernetes.io/docs/concepts/configuration/pod-priority-preemption/
  #priorityClassName: PRIORITYCLASS
  # disables automatic update of oneagent pods in case a new version is available
  #disableAgentUpdate: true
  # Enable management of Istio service entries and virtual services for DESK endpoints to allow for OneAgent monitoring egress traffic to your DESK environment
  #enableIstio: false

Alternatively, you can use the snippet from the GitHub repository.

$ curl -o cr.yaml https://raw.githubusercontent.com/DESK/desk-oneagent-operator/$LATEST_RELEASE/deploy/cr.yaml

Adapt the values of the custom resource as indicated in the following table.

Parameter	Description	Default value
`apiUrl`	DESK SaaS: Replace `ENVIRONMENTID` with your DESK environment ID in `https://ENVIRONMENTID.live.desk.com/api`. DESK Managed: Provide your DESK Server URL (`https://<YourDESKServerURL>/e/<ENVIRONMENTID>/api`)
`tokens`	Name of the secret that holds the API and PaaS tokens from above.	Name of custom resource (`.metadata.name`) if unset
`args`	Parameters to be passed to the OneAgent installer. All the command line parameters of the installer are supported, with the exception of `INSTALL_PATH`. We recommend to set `APP_LOG_CONTENT_ACCESS=1`	[]
`env`	Environment variables for OneAgent container.	[]

Notes:

If you're rolling out DESK OneAgent to Pivotal Container Service clusters, you'll need to add the following entry to the env section in the custom resource.
```
env:
 - name: ONEAGENT_ENABLE_VOLUME_STORAGE
   value: "true"
 - name: ONEAGENT_CONTAINER_STORAGE_PATH
   value: /var/vcap/store
```
If you're rolling out DESK OneAgent to SUSE CaaS clusters, you'll need to add the following entry to the env section in the custom resource.
```
env:
 - name: ONEAGENT_ENABLE_VOLUME_STORAGE
   value: "true"
```

Other parameters...

Parameter	Description	Default value
`skipCertCheck`	Disable certificate validation checks for installer download and API communication. Set to `true` if you want to skip any certification validation checks.	`false`
`nodeSelector`	Keep empty default value. If you want to roll out OneAgent to specific nodes only, provide the `nodeSelectors` here. Refer to Kubernetes docs for details.	{}
`tolerations`	Keep default value to also roll out the OneAgent to master nodes if possible. If you want to apply additional tolerations to OneAgent pods for tainted nodes, provide them here. Refer to Kubernetes docs for details.	[]
`image`	Define the OneAgent image to be taken. Defaults to the publicly available OneAgent image on Docker Hub. In order to use the certified OneAgent image from Red Hat Container Catalog you need to set `.spec.image` to `registry.connect.redhat.com/desk/oneagent` in the custom resource and provide image pull secrets as shown in the next step.	`docker.io/desk/oneagent:latest` if unset
`resources`	Resource requests/limits for the OneAgent pods. These settings heavily depend on size of worker nodes and workloads. Please adjust to fit your needs.	{}
`priorityClassName`	Priority class for OneAgent pod. Refer to Kubernetes docs.
`disableAgentUpdate`	Disable the Operator's auto-update feature for OneAgent pods.	`false`
`enableIstio`	Enable management of Istio service entries and virtual services for DESK endpoints to allow for OneAgent monitoring egress traffic to your DESK environment	`false`

Create the custom resource

$ kubectl create -f cr.yaml

Limitations

The same limitations apply as when deploying OneAgent as a Docker container, except the auto-update. The operator makes sure OneAgents are properly updated.

Prepare DaemonSet

The first step is to obtain the location for ONEAGENT_INSTALLER_SCRIPT_URL. This information is presented to you during DESK OneAgent installation.

Locate your installer URL

To get your ONEAGENT_INSTALLER_SCRIPT_URL

Select Deploy DESK from the navigation menu.
Click Start installation and select Linux.
Copy the URL, shown below. This is your ONEAGENT_INSTALLER_SCRIPT_URL.

Install DaemonSet

Download or copy the desk-oneagent.yml Kubernetes template.

desk-oneagent.yml

Download

apiVersion: extensions/v1beta1
kind: DaemonSet
metadata:
  name: desk-oneagent
spec:
  template:
    metadata:
      labels:
        name: desk-oneagent
    spec:
      hostPID: true
      hostIPC: true
      hostNetwork: true
      nodeSelector:
        beta.kubernetes.io/os: linux
      volumes:
      - name: host-root
        hostPath:
          path: /
      containers:
      - name: desk-oneagent
        image: desk/oneagent
        env:
        - name: ONEAGENT_INSTALLER_SCRIPT_URL
          value: "REPLACE_WITH_YOUR_URL"
        - name: ONEAGENT_INSTALLER_SKIP_CERT_CHECK
          value: "false"
        args:
        - "APP_LOG_CONTENT_ACCESS=1"
        volumeMounts:
        - name: host-root
          mountPath: /mnt/root
        securityContext:
          privileged: true

Note: The APP_LOG_CONTENT_ACCESS parameter is passed to the OneAgent installer and, when set to true (or 1), allows OneAgent to access log files for the purpose of log monitoring. Other parameters may be used in a similar way.

Deploy DESK OneAgent using the created file desk-oneagent.yml.

$ kubectl create -f desk-oneagent.yml --namespace=kube-system
daemonset "desk-oneagent" created

Verify that the desk-oneagent DaemonSet has deployed pods to the cluster nodes successfully:

$ kubectl get pods --namespace=kube-system
NAME                       READY     STATUS              RESTARTS   AGE
desk-oneagent-abcde   1/1       Running             0          1m

$ kubectl logs -f desk-oneagent-abcde
09:46:18 Using volume-based storage
09:46:18 Started agent deployment as a Docker container, PID 1234.
09:46:18 Downloading agent to /tmp/DESK-OneAgent-Linux.sh via https://EnvironmentID.live.desk.com/api/v1/deployment/installer/agent/unix/default/latest?Api-Token=***&arch=x86&flavor=default
09:46:21 Download complete
09:46:21 Downloaded version: 1.x
09:46:21 Validating downloaded agent installer
09:46:23 Verification successful
...

Limitations

The same limitations apply as when deploying OneAgent as a Docker container.