Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

feat: Update k8s-agent-operator.mdx #18963

Merged
merged 4 commits into from
Oct 15, 2024
Merged

feat: Update k8s-agent-operator.mdx #18963

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2a48b99
Update k8s-agent-operator.mdx
ramkrishankumarN Oct 15, 2024
66e0b71
Update src/content/docs/kubernetes-pixie/kubernetes-integration/insta…
ramkrishankumarN Oct 15, 2024
83f6ec5
Update k8s-agent-operator.mdx
jeff-colucci Oct 15, 2024
e93ab01
Update k8s-agent-operator.mdx
jeff-colucci Oct 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
276 changes: 165 additions & 111 deletions ...ocs/kubernetes-pixie/kubernetes-integration/installation/k8s-agent-operator.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,20 +27,6 @@ Before installing the operator, check the following:

* [Kubectl](https://kubernetes.io/docs/tasks/tools/): You have to configure it to communicate with your cluster.

* [Certificate manager](https://cert-manager.io/): You have to install it in the cluster.

### Installation of the `cert-manager` dependency [#install-cert-manager]

To install the certificate manager dependency, run these commands:

```shell
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 [#install-k8s-operator]

Depending on what you need, you can choose to install the agent operator independently or together with our K8s integrations.
Expand Down Expand Up @@ -77,137 +63,205 @@ helm upgrade --install newrelic-bundle newrelic/nri-bundle \
To install the Kubernetes agent operator with the default configuration, run these commands:

```shell
helm repo add newrelic-k8s https://newrelic.github.io/k8s-agents-operator
helm upgrade --install k8s-agents-operator newrelic-k8s/k8s-agents-operator \
helm repo add k8s-agents-operator https://newrelic.github.io/k8s-agents-operator
helm upgrade --install k8s-agents-operator k8s-agents-operator/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](https://github.com/newrelic/k8s-agents-operator/tree/main/charts/k8s-agents-operator#values) chart.

## Configuring a namespace to enable the operator [#configuring-namespace]
## Monitored namespaces [#monitored-namespaces]

Each namespace requires a two-step process to enable automatic instrumentation of applications deployed within it.
A Kubernetes secret will automatically be replicated from the operator's namespace into all namespaces that monitor a pod. Inside the CRD YAML file, specify which APM agents you want to instrument. All available APM agent docker images and corresponding tags are listed on DockerHub:

1. Create a secret containing a valid [New Relic ingest license key](/docs/apis/intro-apis/new-relic-api-keys/#license-key) for each namespace you want the operator to instrument.
* [Java](https://hub.docker.com/repository/docker/newrelic/newrelic-java-init/general)
* [Node](https://hub.docker.com/repository/docker/newrelic/newrelic-node-init/general)
* [Python](https://hub.docker.com/repository/docker/newrelic/newrelic-python-init/general)
* [.NET](https://hub.docker.com/repository/docker/newrelic/newrelic-dotnet-init/general)
* [Ruby](https://hub.docker.com/repository/docker/newrelic/newrelic-ruby-init/general)

```shell
kubectl create secret generic newrelic-key-secret \
--namespace NAMESPACE_TO_MONITOR \
--from-literal=new_relic_license_key=YOUR_NEW_RELIC_INGEST_LICENSE_KEY
```
For .NET
```yaml
apiVersion: newrelic.com/v1alpha2
kind: Instrumentation
metadata:
name: newrelic-instrumentation-dotnet
spec:
agent:
language: dotnet
image: newrelic/newrelic-dotnet-init:latest
# env: ...
```
For Java

Make sure to replace `YOUR_NEW_RELIC_INGEST_LICENSE_KEY` with your valid New Relic license key.
```yaml
apiVersion: newrelic.com/v1alpha2
kind: Instrumentation
metadata:
name: newrelic-instrumentation-java
namespace: newrelic
spec:
agent:
language: java
image: newrelic/newrelic-java-init:latest
# env: ...
```

2. Apply the following Custom Resource Definition (CRD) to each namespace you want to auto instrument. Run this command:
For NodeJS

```shell
kubectl apply -f YOUR_YAML_FILE -n NAMESPACE_TO_MONITOR
```
```yaml
apiVersion: newrelic.com/v1alpha2
kind: Instrumentation
metadata:
name: newrelic-instrumentation-nodejs
namespace: newrelic
spec:
agent:
language: nodejs
image: newrelic/newrelic-node-init:latest
# env: ...
```

Inside the CRD YAML file, specify which APM agents you want to instrument. All available APM agent docker images and corresponding tags are listed on DockerHub:
For Python

* [Java](https://hub.docker.com/repository/docker/newrelic/newrelic-java-init/general)
* [Node](https://hub.docker.com/repository/docker/newrelic/newrelic-node-init/general)
* [Python](https://hub.docker.com/repository/docker/newrelic/newrelic-python-init/general)
* [.NET](https://hub.docker.com/repository/docker/newrelic/newrelic-dotnet-init/general)
* [Ruby](https://hub.docker.com/repository/docker/newrelic/newrelic-ruby-init/general)
```yaml
apiVersion: newrelic.com/v1alpha2
kind: Instrumentation
metadata:
name: newrelic-instrumentation-python
namespace: newrelic
spec:
agent:
language: python
image: newrelic/newrelic-python-init:latest
# env: ...
```

```yaml
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-node-init:latest
python:
image: newrelic/newrelic-python-init:latest
dotnet:
image: newrelic/newrelic-dotnet-init:latest
ruby:
image: newrelic/newrelic-ruby-init:latest
```

## Enable automatic APM instrumentation in applications [#enable-apm-instrumentation]

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

See the currently supported annotations:
For Ruby

```shell
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"
```yaml
apiVersion: newrelic.com/v1alpha2
kind: Instrumentation
metadata:
name: newrelic-instrumentation-ruby
namespace: newrelic
spec:
agent:
language: ruby
image: newrelic/newrelic-ruby-init:latest
# env: ...
```

For environment specific configurations

```yaml
apiVersion: newrelic.com/v1alpha2
kind: Instrumentation
metadata:
name: newrelic-instrumentation-lang
namespace: newrelic
spec:
agent:
env:
# Example New Relic agent supported environment variables
- name: NEW_RELIC_LABELS
value: "environment:auto-injection"
# Example setting the pod name based on the metadata
- name: NEW_RELIC_POD_NAME
valueFrom:
fieldRef:
fieldPath: metadata.name
# Example overriding the appName configuration
- name: NEW_RELIC_APP_NAME
value: "$(NEW_RELIC_LABELS)-$(NEW_RELIC_POD_NAME)"
```

Targeting everything in a specific namespace with a label

```yaml
apiVersion: newrelic.com/v1alpha2
kind: Instrumentation
metadata:
name: newrelic-instrumentation-lang
namespace: newrelic
spec:
#agent: ...
namespaceLabelSelector:
matchExpressions:
- key: "app.newrelic.instrumentation"
operator: "In"
values: ["java"]
```

Targeting a pod with a specific label

```yaml
apiVersion: newrelic.com/v1alpha2
kind: Instrumentation
metadata:
name: newrelic-instrumentation-lang
namespace: newrelic
spec:
# agent: ...
podLabelSelector:
matchExpressions:
- key: "app.newrelic.instrumentation"
operator: "In"
values: ["dotnet"]
```

See this example of deployment with annotation to instrument the Java agent:
Using a secret with a non-default name

```yaml
apiVersion: apps/v1
kind: Deployment
apiVersion: newrelic.com/v1alpha2
kind: Instrumentation
metadata:
name: spring-petclinic
name: newrelic-instrumentation-lang
namespace: newrelic
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
# agent: ...
licenseKeySecret: the-name-of-the-custom-secret
```

In the example above, we show how you can configure the agent settings globally using environment variables. See each agent's configuration documentation for available configuration options:
* [Java](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file/)
* [Node](https://docs.newrelic.com/docs/apm/agents/nodejs-agent/installation-configuration/nodejs-agent-configuration/)
* [Python](https://docs.newrelic.com/docs/apm/agents/python-agent/configuration/python-agent-configuration/)
* [.NET](https://docs.newrelic.com/docs/apm/agents/net-agent/configuration/net-agent-configuration/)
* [Ruby](https://docs.newrelic.com/docs/apm/agents/ruby-agent/configuration/ruby-agent-configuration/)

### cert-manager

The K8s Agents Operator supports the use of [`cert-manager`](https://github.com/cert-manager/cert-manager) if preferred.

Install the [`cert-manager`](https://github.com/cert-manager/cert-manager) Helm chart:
```shell
helm install cert-manager jetstack/cert-manager \
--namespace cert-manager \
--create-namespace \
--set crds.enabled=true
```

This example file shows how to configure the agent settings globally with environment variables. Refer to each agent's configuration docs for all available configuration options:
In your `values.yaml` file, set `admissionWebhooks.autoGenerateCert.enabled: false` and `admissionWebhooks.certManager.enabled: true`. Then install the chart as normal.

* [Java](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file/)
* [Node](https://docs.newrelic.com/docs/apm/agents/nodejs-agent/installation-configuration/nodejs-agent-configuration/)
* [Python](https://docs.newrelic.com/docs/apm/agents/python-agent/configuration/python-agent-configuration/)
* [.NET](https://docs.newrelic.com/docs/apm/agents/net-agent/configuration/net-agent-configuration/)
* [Ruby](https://docs.newrelic.com/docs/apm/agents/ruby-agent/configuration/ruby-agent-configuration/)
## Available Chart Releases

Global agent settings can be overridden in your deployment manifest if a different configuration is required.
To see the available charts:
```shell
helm search repo k8s-agents-operator
```

## Upgrade APM instrumentation in applications [#upgrade-apm-instrumention]

By default, the Kubernetes agent operator automatically installs the latest available versions of the corresponding [APM agent](/docs/apm/new-relic-apm/getting-started/introduction-apm/).

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.
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 if the CR is already loaded inside the operator

## Remove APM instrumentation in applications [#remove-apm-instrumentation]

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.
To remove the APM instrumentation in an application, you must remove the matching label selector inside either the `podLabelSelector` or `namespaceLabelSelector` used by the Kubernetes agent operator, then restart the deployment. In a few seconds, you will see that the APM agents have been automatically removed.

## Updating the Kubernetes agent operator [#upgrading-k8s-operator]

Expand Down Expand Up @@ -319,7 +373,7 @@ If your applications are not instrumented, you should check the following:
kubectl get instrumentation -n NAMESPACE
```

* Check that the pod has the annotations that enable automatic instrumentation.
* Check that the pod has the required labels that enable automatic instrumentation through CR when using `podLabelSelector`. Similarly, check that the namespace has the required labels when using `namespaceLabelSelector` inside the CR.

```shell
kubectl get pod POD_NAME -n NAMESPACE -o jsonpath='{.metadata.annotations}'
Expand Down
Loading