Kubernetes agent operator

The Kubernetes agent operator streamlines full-stack observability for Kubernetes environments by automating APM instrumentation alongside Kubernetes agent deployment. By enabling APM auto instrumentation, developers no longer need to manually manage APM agents. The Kubernetes agent operator will automatically installs, upgrades, and removes APM agents.

It currently supports Java, .NET, Node.js, Python, and Ruby with additional languages (PHP and Go) on the way.

Before you begin

Before installing the operator, check the following:

• Helm: You must install it to use the charts. See the Helm documentation if you need help getting started.

• Kubectl: You have to configure it to communicate with your cluster.

• Certificate manager: You have to instal it in the cluster.

Installation of the cert-manager dependency

To install the certificate manager dependency, run these commands:

$
helm repo add jetstack https://charts.jetstack.io
$
    helm install cert-manager jetstack/cert-manager \
>
        --namespace cert-manager \
>
        --create-namespace \
>
        --set crds.enabled=true

Installation of the Kubernetes agent operator

Depending on what you need, you can choose to install the agent operator independently or together with our K8s integrations. We strongly recommend that you install it along with the K8s integration to take advantage of our full stack obsevability experience.

We strongly recommend to install it together with the Kubernetes integration to take advantage of our entire full stack obsevability experience.

Bundle installation in addition to the Kubernetes integration (recommended)

The Kubernetes agent operator chart is integrated as part of the nri-bundle chart, which manages the installation of all the components needed to enable a full Kubernetes observability.

Add the k8s-agents-operator.enabled=true parameter to your helm command or include it in a values.yaml file.

See the Install the Kubernetes integration page for more information about using Helm or check out the nri-bundle chart.

See this sample of Helm command using parameters:

$
helm repo add newrelic https://helm-charts.newrelic.com
$

$
   helm upgrade --install newrelic-bundle newrelic/nri-bundle \
>
      --set global.licenseKey=<NEW RELIC INGEST LICENSE KEY> \
>
      --set global.cluster=<CLUSTER_NAME> \
>
      --namespace=newrelic \
>
      --set newrelic-infrastructure.privileged=true \
>
      --set global.lowDataMode=true \
>
      --set kube-state-metrics.image.tag=${KSM_IMAGE_VERSION} \
>
      --set kube-state-metrics.enabled=true \
>
      --set kubeEvents.enabled=true \
>
      --set k8s-agents-operator.enabled=true \
>
      --create-namespace

Standalone installation

To install the Kubernetes agent operator with the default configuration, run these commands:

$
helm repo add newrelic-k8s https://newrelic.github.io/k8s-agents-operator
$
    helm upgrade --install k8s-agents-operator newrelic-k8s/k8s-agents-operator \
>
        --namespace newrelic \
>
        --create-namespace \
>
        --set licenseKey=<YOUR_NEW_RELIC_INGEST_LICENSE_KEY>

For a complete list of configuration options, see the README chart.

Configuring a namespace to enable the operator

Each namespace requires a two-step process to enable automatic instrumentation of applications deployed within it.

1. Create a secret containing a valid New Relic ingest license key for each namespace you want the operator to instrument.

   bash

   Copiar

   $
   kubectl create secret generic newrelic-key-secret \
   >
           --namespace <NAMESPACE_TO_MONITOR> \
   >
           --from-literal=new_relic_license_key=<YOUR_NEW_RELIC_INGEST_LICENSE_KEY>

   Make sure to replace <YOUR_NEW_RELIC_INGEST_LICENSE_KEY> with your valid New Relic license key.

2. Apply the following CRD to each namespace you want to auto instrument. Run this command:

   bash

   Copiar

   $
   kubectl apply -f <YOUR_YAML_FILE> -n <NAMESPACE_TO_MONITOR>

   YAML file to apply:

   apiVersion: newrelic.com/v1alpha1
   kind: Instrumentation
   metadata:
       labels:
           app.kubernetes.io/name: instrumentation
           app.kubernetes.io/created-by: k8s-agents-operator
       name: newrelic-instrumentation
   spec:
       java:
           image: newrelic/newrelic-java-init:latest
           # env:
           # Example New Relic agent supported environment variables
           # - name: NEW_RELIC_LABELS
           #   value: "environment:auto-injection"
           # Example overriding the appName configuration
           # - name: NEW_RELIC_POD_NAME
           #   valueFrom:
           #     fieldRef:
           #       fieldPath: metadata.name
           # - name: NEW_RELIC_APP_NAME
           #   value: "$(NEW_RELIC_LABELS)-$(NEW_RELIC_POD_NAME)"
       nodejs:
           image: newrelic/newrelic-nodejs-init:latest
       python:
           image: newrelic/newrelic-python-init:latest
       dotnet:
           image: newrelic/newrelic-dotnet-init:latest
       ruby:
           image: newrelic/newrelic-ruby-init:latest

   Copiar

Enable automatic APM instrumentation in applications

The Kubernetes agent operator looks for language-specific annotations when scheduling your pods to know which applications to monitor.

See the currently supported annotations:

$
instrumentation.newrelic.com/inject-java: "true"
$
    instrumentation.newrelic.com/inject-nodejs: "true"
$
    instrumentation.newrelic.com/inject-python: "true"
$
    instrumentation.newrelic.com/inject-dotnet: "true"
$
    instrumentation.newrelic.com/inject-ruby: "true"

See this example of deployment with annotation to instrument the Java agent:

apiVersion: apps/v1
    kind: Deployment
    metadata:
        name: spring-petclinic
    spec:
      selector:
        matchLabels:
          app: spring-petclinic
      replicas: 1
      template:
        metadata:
          labels:
            app: spring-petclinic
          annotations:
            instrumentation.newrelic.com/inject-java: "true"
        spec:
          containers:
            - name: spring-petclinic
              image: ghcr.io/pavolloffay/spring-petclinic:latest
              ports:
                - containerPort: 8080
              env:
              - name: NEW_RELIC_APP_NAME
                value: spring-petclinic-demo

Upgrade APM instrumentation in applications

By default, the Kubernetes agent operator automatically installs the latest available versions of the corresponding APM agent.

Once an application is monitored, it's not automatically upgraded to a newer version unless the user chooses to upgrade. You can seamlessly upgrade the application to a newer version by simply redeploying the pods or restarting your deployment.

Remove APM instrumentation in applications

To remove the APM instrumentation in an application, you must remove the annotations used by the Kubernetes agent operator. In a few seconds, you will see that the APM agents have been automatically removed.

Updating the Kubernetes agent operator

Bundle installation

Run a upgrade of the nri-bundle chart with the following parameter:

$
k8s-agents-operator.enabled=true

Standalone installation

Run the helm upgrade command to update to a newer version of the Kubernetes agent operator.

$
helm upgrade k8s-agents-operator newrelic/k8s-agents-operator -n newrelic

Uninstalling the Kubernetes agent operator

Bundle installation

Uninstall the nri-bundle chart or if you only want to remove the operator, run a helm upgrade with the following parameter:

$
k8s-agents-operator.enabled=false

Standalone installation

To uninstall and delete the Kubernetes agent operator, run this command:

$
helm uninstall k8s-agents-operator -n newrelic

Find and use data

• Get insights of your applications and resolve incidents using the APM summary page.

• Check out the Kubernetes summary page. It provides Kubernetes insights in the context of your monitored applications.

Frequently Asked Questions

Troubleshooting

If your applications are not instrumented, you should check the following:

• Please be sure to redeploy or deploy new applications after the operator has been installed. Please be advised that the operator only auto-instruments new applications deployed in the cluster.

• Check that the secret and the instrumentation CRD are installed in the app's namespace.

  bash

  Copiar

  $
  kubectl get secrets -n <NAMESPACE>
  $
      kubectl get instrumentation -n <NAMESPACE>

• Check that the pod has the annotations that enable automatic instrumentation.

  bash

  Copiar

  $
  kubectl get pod <POD> -n <NAMESPACE>  -o jsonpath='{.metadata.annotations}'

• Get logs from the agent operator pod.

  bash

  Copiar

  $
  kubectl logs <AGENT_OPERATOR_POD> -n newrelic

• Ensure the init container has been injected and sucessfully executed inside the application's pod.

  bash

  Copiar

  $
  kubectl describe pod <POD> -n <NAMESPACE>

Support

The Kubernetes agent operator currently supports the latest version of these APM agents: Java, .NET, Node.js, Python, and Ruby.

Once the operator is on general availability, the most recent 3 versions of each of the APM agents will be supported.

For issues with the Kubernetes agent operator:

• Review the issues section on GitHub for any similar problems or consider opening a new issue.

• You can reach out to the New Relic support team for assistance.