Skip to content

Commit

Permalink
chore(docs): Review and improve existing Kubernetes-related documenta…
Browse files Browse the repository at this point in the history 
…tion
  • Loading branch information
@jsubirat @sunnyzanchi
jsubirat authored and sunnyzanchi committed Jun 2, 2023
1 parent d2cf6de commit 7bebf22
Show file tree
Hide file tree
Showing 6 changed files with 61 additions and 59 deletions.
6 changes: 3 additions & 3 deletions ...ixie/kubernetes-integration/get-started/introduction-kubernetes-integration.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ src={kubernetesClusterExplorer}
**[one.newrelic.com](https://one.newrelic.com/all-capabilities) > Kubernetes > Kubernetes cluster explorer**: The cluster explorer is our powerful, fully visual answer to the challenges associated with running Kubernetes at a large scale.
</figcaption>

You can see the power of the Kubernetes integration in the [cluster explorer](/docs/integrations/kubernetes-integration/cluster-explorer/kubernetes-cluster-explorer), where the full picture of a cluster is made available on a single screen: nodes and pods are visualised according to their health and performance, with pending and alerting nodes in the innermost circles. [Predefined alert conditions](/docs/integrations/kubernetes-integration/kubernetes-events/kubernetes-integration-predefined-alert-policy) help you troubleshoot issues right from the start. Clicking each node reveals its status and how each app is performing.
You can see the power of the Kubernetes integration in the [cluster explorer](/docs/integrations/kubernetes-integration/cluster-explorer/kubernetes-cluster-explorer), where the full picture of a cluster is made available on a single screen: nodes and pods are visualised according to their health and performance, with pending and alerting nodes in the innermost circles. [Predefined alert conditions](/docs/integrations/kubernetes-integration/kubernetes-events/kubernetes-integration-predefined-alert-policy) help you troubleshoot issues right from the start. Clicking each node or pod reveals their status, how each app is performing and allows accessing their logs easily.

You'll be able to configure Kubernetes to suit your environment after you create a New Relic account (it's free, forever!) and [install our Kubernetes integration](/docs/kubernetes-pixie/kubernetes-integration/installation/kubernetes-integration-install-configure/).

Expand Down Expand Up @@ -83,8 +83,8 @@ These features are in addition to the data New Relic already reports for [contai

## Bring your cluster logs to New Relic [#k8s-logs]

Our Kubernetes plugin for log monitoring can collect all your cluster's logs and send them to our platform, so that you can set up new alerts and charts. To set it up, check the **Log data** box in step 3 of [our install wizard](/docs/integrations/kubernetes-integration/installation/kubernetes-installation-configuration#install-wizard). For detailed information, see our [log forwarding documentation](/docs/logs/forward-logs/kubernetes-plugin-log-forwarding/) for Kubernetes.
Our Kubernetes plugin for log monitoring can collect all your cluster's logs and send them to our platform, so that you can set up new alerts and charts. To set it up, check the **Gather Log Data** box in step 3 of [our install wizard](/docs/integrations/kubernetes-integration/installation/kubernetes-installation-configuration#install-wizard). For detailed information, see our [log forwarding documentation](/docs/logs/forward-logs/kubernetes-plugin-log-forwarding/) for Kubernetes.

## Check the source code [#source-code]

This integration is open source software. That means you can [browse its source code](https://github.com/newrelic/nri-kubernetes) and send improvements, or you can create your own fork and build it. For more information, see the [README](https://github.com/newrelic/nri-kubernetes/blob/main/README.md).
This integration is open source software. That means you can [browse its source code](https://github.com/newrelic/nri-kubernetes) and send improvements, or you can create your own fork and build it. For more information, see the [README](https://github.com/newrelic/nri-kubernetes/blob/main/README.md).
55 changes: 41 additions & 14 deletions ...bernetes-integration/installation/install-kubernetes-integration-using-helm.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,12 +39,12 @@ To install the Kubernetes integration using Helm, you will need your New Relic <
```

<Callout variant="important">
Note these values somewhere safe, as you will need them later during the installation process.
Keep these values somewhere safe, as you will need them later during the installation process.
</Callout>

## Install Kubernetes integration with Helm [#install-k8-helm]

New Relic has several charts for the different components which offer different features for the platform:
New Relic has several Helm charts for the different components which offer different features for the platform:

* [`newrelic-infrastructure`](https://github.com/newrelic/nri-kubernetes/tree/main/charts/newrelic-infrastructure): Contains the main Kubernetes integration and the infrastructure agent. This is the core component for the New Relic Kubernetes experience, responsible for reporting most of the data that is surfaced in the Kubernetes Dashboard and the Kubernetes Cluster Explorer.
* [`newrelic-logging`](https://github.com/newrelic/helm-charts/tree/master/charts/newrelic-logging): Provides a DaemonSet with New Relic's [Fluent Bit](https://fluentbit.io/) output [plugin](https://github.com/newrelic/newrelic-fluent-bit-output) to easily forward your logs to [New Relic](https://docs.newrelic.com/docs/logs/new-relic-logs/get-started/introduction-new-relic-logs).
Expand All @@ -53,9 +53,13 @@ New Relic has several charts for the different components which offer different
* [`nri-metadata-injection`](https://github.com/newrelic/k8s-metadata-injection/tree/main/charts/nri-metadata-injection): Sets up a minimal `MutatingAdmissionWebhook` that injects a couple of environment variables in the containers. These contain metadata about the cluster and New Relic installation and will be later picked up by applications instrumented using APM, allowing to [correlate APM and infrastructure data](/docs/integrations/kubernetes-integration/link-your-applications/link-your-applications-kubernetes/).
* [`nri-statsd`](https://github.com/newrelic/helm-charts/tree/master/charts/nri-statsd): New Relic StatsD integration.

For convenience, New Relic provides the [`nri-bundle`](https://github.com/newrelic/helm-charts/tree/master/charts/nri-bundle) chart, which pulls a selectable set of the charts mentioned above. `nri-bundle` can also install Kube State Metrics and Pixie for you if needed.
For convenience, New Relic provides the [`nri-bundle`](https://github.com/newrelic/helm-charts/tree/master/charts/nri-bundle) chart, which acts as a wrapper or a meta-package for the individual charts mentioned above. While it's possible to install them separately, we strongly recommend doing so using the [`nri-bundle`](https://github.com/newrelic/helm-charts/tree/master/charts/nri-bundle) instead, because:
- It provides full control over which components are installed.
- It ensures that their installed versions are compatible with each other.
- It ensures that their configuration values are consistent across the installed charts.
- You can still configure each component individually as a [Helm dependency](https://helm.sh/docs/chart_template_guide/subcharts_and_globals/#overriding-values-from-a-parent-chart), using the configuration parameters mentioned [here](#configure).

While it's possible to install those charts separately, we strongly recommend using the [`nri-bundle`](https://github.com/newrelic/helm-charts/tree/master/charts/nri-bundle) chart for Kubernetes deployments, as it ensures that values across all the charts are consistent and provides full control over which components are installed, as well as the possibility to configure all of them as [Helm dependencies](https://helm.sh/docs/chart_template_guide/subcharts_and_globals/#overriding-values-from-a-parent-chart). This is the same chart that is used and referenced by our [Kubernetes guided install](/docs/kubernetes-pixie/kubernetes-integration/installation/kubernetes-integration-install-configure#guided-install).
The `nri-bundle` chart is the one that is installed and configured by our [Kubernetes guided install](/docs/kubernetes-pixie/kubernetes-integration/installation/kubernetes-integration-install-configure#guided-install).

### Installing and configuring `nri-bundle` with Helm

Expand Down Expand Up @@ -131,11 +135,12 @@ While it's possible to install those charts separately, we strongly recommend us
```shell
helm upgrade --install newrelic-bundle newrelic/nri-bundle \
--namespace newrelic --create-namespace \
-f values-newrelic.yaml
-f values-newrelic.yaml
```

<Callout variant="important">
Make sure you're using Kubernetes version 1.26.x or [a lower version that we support](/docs/kubernetes-pixie/kubernetes-integration/get-started/kubernetes-integration-compatibility-requirements).

Kubernetes 1.27.x is currently in an experimental release phase. If you find any issues, please contact support @ newrelic.com.
</Callout>
6. Check that pods are being deployed and reach a stable state:
Expand All @@ -154,7 +159,7 @@ You should see:
6. One `prometheus-agent` pod, if you enabled the [Prometheus agent](/docs/infrastructure/prometheus-integrations/install-configure-prometheus-agent/install-prometheus-agent) integration.
7. One `newrelic-newrelic-logging` pod for each node in your cluster, if you enabled the Logging integration.

### Install with Helm 2 and nri-bundle (legacy)
### Install with Helm 2 and nri-bundle (legacy, deprecated)

<CollapserGroup>
<Collapser
Expand Down Expand Up @@ -246,33 +251,55 @@ You should see:

Our `nri-bundle` chart. whose installation instructions can be found above, acts as a wrapper or a meta-package for a couple of other charts, which are the ones containing the components for our solution. By offering such a wrapper we can provide a controlled set of our components with versions that we know are compatible with each other, while keeping the component's charts relatively simple.

To configure the individual integration components, you must use Helm's dependency system, which simply means that configuration for the children charts must be put under a section with the name of said chart. For example, to configure the `newrelic-infrastructure` chart, you would add the following to the `values-newrelic.yaml`:
The [`nri-bundle`](https://github.com/newrelic/helm-charts/tree/master/charts/nri-bundle) chart wraps [multiple individual charts](#install-k8-helm) to gather different telemetry data and send it to New Relic. The bundle allows to selectively enable the desired child charts depending on your needs. To configure each individual component, you must use [Helm's dependency system](https://helm.sh/docs/chart_template_guide/subcharts_and_globals/#overriding-values-from-a-parent-chart), which in short means that the configuration for each children chart must be placed under a separate section (named after each child chart) in the [values-newrelic.yml file](https://helm.sh/docs/chart_template_guide/values_files/). For example, to configure the `newrelic-infrastructure` chart, you would add the following to the `values-newrelic.yaml`:

```yaml
# General settings that apply to all the children charts
global:
licenseKey: _YOUR_NEW_RELIC_LICENSE_KEY_
cluster: _K8S_CLUSTER_NAME_

# ... Other settings as shown above

# Configuration for newrelic-infrastructure
# Specific configuration for the newrelic-infrastructure children chart
newrelic-infrastructure:
verboseLog: true # Enable debug logs
privileged: false # Install with minimal privileges
# Other options from https://github.com/newrelic/helm-charts/tree/master/charts/newrelic-infrastructure-v3

# Specific configuration for the newrelic-logging children chart
newrelic-logging:
fluentBit:
retryLimit: 10
```

The full list of flags you can tweak (such as [scrape-interval](/docs/new-relic-solutions/observability-maturity/operational-efficiency/data-governance-optimize-ingest-guide#k8s-integration)) is in our chart's repository:
You can also pass children chart options through the command line by prefixing them with the children chart name and replace the nesting by dots:

```
helm upgrade --install newrelic-bundle newrelic/nri-bundle \
--namespace=newrelic \
--set global.licenseKey=_YOUR_NEW_RELIC_LICENSE_KEY_ \
--set global.cluster=_K8S_CLUSTER_NAME_ \
--set newrelic-infrastructure.privileged=false \
--set newrelic-infrastructure.verboseLog=true \
--set newrelic-logging.fluentBit.retryLimit=10 \
```

The full list of flags you can tweak (such as [scrape-interval](/docs/new-relic-solutions/observability-maturity/operational-efficiency/data-governance-optimize-ingest-guide#k8s-integration)) for each children chart can be found in their respective repositories:

* [`newrelic-infrastructure`](https://github.com/newrelic/nri-kubernetes/tree/main/charts/newrelic-infrastructure)
* Configure debug logs, privilege mode, control plane monitoring, etc.
* Configure debug logs, privilege mode, control plane monitoring, etc.
* [`nri-kube-events`](https://github.com/newrelic/nri-kube-events/tree/main/charts/nri-kube-events)
* [`nri-metadata-injection`](https://github.com/newrelic/k8s-metadata-injection/tree/main/charts/nri-metadata-injection)
* Configure how the webhook for APM linkage is deployed.
* Configure which Prometheus endpoints are scraped.
* Configure how the webhook for APM linkage is deployed.
* Configure which Prometheus endpoints are scraped.
* [`newrelic-logging`](https://github.com/newrelic/helm-charts/tree/master/charts/newrelic-logging)
* Configure which logs are sent to New Relic.
* Configure which logs or log attributes are sent to New Relic.

<Callout variant="tip">
When specifying configuration options for the child charts, you must place them under a section named after the chart name in your `values-newrelic.yaml`.
</Callout>

<Callout variant="tip">
Remember that when specifying options for these charts, you must put them under the chart name in your `values-newrelic.yaml`.
To pass children chart options through the command line, you need to prefix them with the children chart name and replace the nesting by dots.
</Callout>
35 changes: 10 additions & 25 deletions ...ubernetes-integration/installation/kubernetes-integration-install-configure.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,6 @@ signupBanner:
text: Monitor and improve your entire stack. 100GB free. Forever.
---

import kubernetesPivotal from 'images/kubernetes_logo_pivotal.webp'

import kubernetesAks from 'images/kubernetes_logo_aks.webp'

import kubernetesOpenshift from 'images/kubernetes_logo_openshift.webp'
Expand All @@ -38,7 +36,7 @@ import pixieLiveDebugging from 'images/pixie_screenshot-full_live-debugging.webp

import pixieServiceOtelMap from 'images/pixie_screenshot-full_service-otel-map.webp'

The New Relic Kubernetes integration gives you full observability into the health and performance of your environment by leveraging the New Relic infrastructure agent. This agent collects metrics from your cluster alongside various other New Relic integrations such as the [Kubernetes events integration](/docs/integrations/kubernetes-integration/kubernetes-events/install-kubernetes-events-integration), the [Prometheus Agent](/docs/infrastructure/prometheus-integrations/install-configure-prometheus-agent/install-prometheus-agent/), and the [New Relic log plugin](/docs/logs).
The New Relic Kubernetes integration gives you full observability into the health and performance of your environment by leveraging the New Relic infrastructure agent. This agent collects telemetry data from your cluster using several New Relic integrations such as the [Kubernetes events integration](/docs/integrations/kubernetes-integration/kubernetes-events/install-kubernetes-events-integration), the [Prometheus Agent](/docs/infrastructure/prometheus-integrations/install-configure-prometheus-agent/install-prometheus-agent/), and the [New Relic Logs Kubernetes plugin](/docs/logs).

## Why use the guided install? [#why-guided-install]
To install our Kubernetes integration, we recommend that you follow the instructions here for our guided install. We recommend this interactive installation tool for servers, VMs, and [unprivileged](/docs/infrastructure/install-infrastructure-agent/linux-installation/linux-agent-running-modes) environments. Here are some advantages of using the guided install:
Expand Down Expand Up @@ -259,9 +257,9 @@ Once you start the guided install, use the following information to help you mak
id="full-enrichment"
title="Forward all logs with full enrichment"
>
If you prefer more robust data, select this option to fully enrich your logs by adding label and annotation data to your log data.
If you prefer more robust data, select this option to fully enrich your logs by adding label and annotation data.

Here's an example of a enriched log data:
Here's an example of a log with full data enrichment:

```json
[
Expand Down Expand Up @@ -305,24 +303,11 @@ Once you start the guided install, use the following information to help you mak
id="min-enrichment"
title="Forward all logs with minimal enrichment (low data mode)"
>
If you want to prioritize data ingest costs, you can choose to gather log data with minimal enrichment. This option drops labels and annotations from their logs and only shares standard Kubernetes log data such as the name of the cluster, container, namespace, and pod, along with the message and timestamp.

In minimal enrichment, only the following fields are retained:
If you want to prioritize data ingest costs, you can choose to gather log data with minimal enrichment, also known as low data mode. This option drops labels and annotations from your logs and only shares standard Kubernetes log data such as the name of the cluster, container, namespace, and pod, along with the message and timestamp.

```yaml
[FILTER]
Name record_modifier
Match *
Record cluster_name ${CLUSTER_NAME}
Allowlist_key container_name
Allowlist_key namespace_name
Allowlist_key pod_name
Allowlist_key stream
Allowlist_key message
Allowlist_key log
```
When selecting the minimal enrichment mode, only the following log attributes are retained: `cluster_name`, `container_name`, `namespace_name`, `pod_name`, `stream`, `message` and `log`.

Here's an example of minimal log enrichment:
Here's an example of a log with minimal data enrichment:
```json
[
{
Expand Down Expand Up @@ -379,11 +364,11 @@ Once you start the guided install, use the following information to help you mak
</Step>

<Step>
Finalize the Kubernetes installation setup by choosing one of the following:
Finalize the Kubernetes installation setup by choosing one of the following installation methods in the last step of the guided install:

* Run the CLI command
* Use the Helm chart
* Use the manifest
* **Guided Install (recommended)**: this option will automatically download and use the [`newrelic-cli`](https://developer.newrelic.com/automate-workflows/get-started-new-relic-cli/) CLI to install and configure the Kubernetes integration.
* **Helm 3**: use this option if you prefer using [Helm](https://helm.sh/) to install and configure the Kubernetes integration. This option installs the [`nri-bundle` Helm chart](/docs/kubernetes-pixie/kubernetes-integration/installation/install-kubernetes-integration-using-helm/#install-k8-helm), which you can further configure with the options described [here].(/docs/kubernetes-pixie/kubernetes-integration/installation/install-kubernetes-integration-using-helm/#configure).
* **Manifest**: select this option if you prefer generating a Kubernetes manifest in YAML format and manually installing it with [`kubectl`](https://kubernetes.io/docs/reference/kubectl/).
</Step>
</Steps>

Expand Down

0 comments on commit 7bebf22

Please sign in to comment.