Merge pull request #21639 from newrelic/feature/NR-441141-review-docs

Feature/nr 441141 review docs

Author: WriteMayur

src/content/docs/infrastructure-as-code/terraform/agent-control.mdx

@@ -3,30 +3,36 @@ title: "Agent Control setup with Terraform"
 metaDescription: "Agent Control is an agent supervisor that can be used to deploy, update, and manage New Relic agents."
 freshnessValidatedDate: never
 ---
-[New Relic Agent Control](/docs/new-relic-control/agent-control/overview) with Terraform makes the large-scale monitoring with New Relic even easier, especially when dealing with multiple Kubernetes clusters. With Terraform and Helm, you can set up New Relic Agent Control in a specified, repeatable, and scalable way across your entire Kubernetes infrastructure. 
+[New Relic Agent Control](/docs/new-relic-control/agent-control/overview) with Terraform provides a powerful, declarative solution for managing fleets of agents at scale. By using Terraform and Helm together, you can ensure a consistent, repeatable, and scalable approach to deploying New Relic instrumentation across your entire infrastructure, especially when dealing with multiple Kubernetes clusters.
 
 ## Prerequisites [#prereqs]
-Before using this integration in Terraform, ensure you have the following:
-
-- **Helm 3:** Helm version 3 must be installed on your machine. For installation instructions, see [Installing Helm](https://helm.sh/docs/intro/install).
-- **New Relic license key:** You'll need a New Relic license key to report telemetry to your New Relic account.
-- **New Relic user key:** You'll need your [New Relic user key](/docs/apis/intro-apis/new-relic-api-keys/) if you haven't already pulled your `clientID` key and secret.
-- **User permissions:** Your New Relic user has the auth domain manager and org product admin roles.
-- **New Relic OrgId:** The New Relic `OrgId` will identify which organization you are getting your client ID key and secret from.
-- **Kubernetes cluster name:** Have the name of your Kubernetes cluster ready, as it will be referenced during the installation process.
+Before you begin, ensure you have the following:
+
+- **Required Tools:**
+  - **[Terraform](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli)** installed on your machine.
+  - **Helm 3** installed on your machine. For installation instructions, see [Installing Helm](https://helm.sh/docs/intro/install).
+  - **[Terraform Helm Provider](https://registry.terraform.io/providers/hashicorp/helm/latest/docs)** included in your Terraform configuration script for the installation to work.
+
+- **New Relic Credentials:**
+  - **New Relic license key:** You'll need a New Relic license key to report telemetry to your New Relic account.
+  - **New Relic user key:** You'll need your [New Relic user key](/docs/apis/intro-apis/new-relic-api-keys/) if you haven't already pulled your `clientID` key and secret.
+
+- **Configuration Details:**
+  - **New Relic Organization ID:** The New Relic `OrgId` will identify which organization you are getting your client ID key and secret from.
+  - **User permissions:** Your user needs the correct permissions to create a System Identity. This typically requires the Authentication Domain Manager and Org Product Admin roles.
+  - **Kubernetes cluster name:** Have the name of your Kubernetes cluster ready, as it will be referenced during the installation process.
+
 <Callout variant="tip">
   When setting up a new cluster with Terraform, make sure to use the same cluster name during the installation of agent control.
 </Callout>
-- **Helm provider for Terraform:** Include the [Helm provider](https://registry.terraform.io/providers/hashicorp/helm/latest/docs) in your Terraform script for the installation to work.
-- **Terraform:** Make sure you have [Terraform](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli) installed on your machine.
 
-## Compatibility [#compatibility]
+### Kubernetes Compatibility [#compatibility]
 
 To find out which Kubernetes versions are compatible with this solution, refer to the [compatibility](/docs/new-relic-control/agent-control/overview/#compatibility) section in the overview.
 
 ## Install [#installation]
 
-If you don't have your `clientId` and `clientSecret`, fetch them using the following [NerdGraph](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph/) API: 
+If you don't have your `clientId` and `clientSecret`, use the following [NerdGraph](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph/) API call to generate them. This requires your New Relic Admin User Key and Organization ID. 
 
 ```sh
   curl -X POST \
@@ -39,13 +45,13 @@ If you don't have your `clientId` and `clientSecret`, fetch them using the follo
 
 In the command, replace the placeholder values with your `organizationId` and user key. This returns the required credentials that you'll use in your configuration file.
 
-### Step 1
+### Step 1: Create Your Project Directory
 
-Create a directory for your project and place your `main.tf` file inside it. Confirm that you have added the [Helm provider](https://registry.terraform.io/providers/hashicorp/helm/latest/docs) to your Terraform file.
+Create a directory for your project and place your `main.tf` file inside it. This is where you'll define your Terraform resources. Confirm that you have added the [Helm provider](https://registry.terraform.io/providers/hashicorp/helm/latest/docs) to your Terraform file.
 
-### Step 2
+### Step 2: Configure Terraform with the Helm Release
 
-Configure your Terraform script with a Helm release that uses New Relic's charts for Agent Control. See the sample script below:
+Configure your Terraform script with a Helm release that uses New Relic's charts for Agent Control. The following example shows a basic configuration:
 
 ```hcl
 provider "helm" {
@@ -101,37 +107,45 @@ agent-control-deployment:
 To explore all available configuration settings, refer to [`values-newrelic.yaml`](https://github.com/newrelic/helm-charts/blob/master/charts/agent-control/values.yaml).
 
 
-### Step 3
+### Step 3: Run Terraform Commands
 
-Initialize and review the Terraform script:
+Initialize Terraform, review the plan, and apply the changes.
 
   ```shell
+      # Initialize Terraform
       terraform init
   ```
 
   ```shell
+      # Review the changes before applying
       terraform plan
   ```
 
-### Step 4
-
-Apply your changes:
-
   ```shell
+      # Apply the changes to your cluster
       terraform apply
   ```
 
-### Step 5
+### Step 5: Verify the Installation
 
-Check to make sure the agent pods get built out correctly using Kube Control:
+Check to make sure the Agent Control pods and any configured agents are running correctly in their respective namespaces.
 
   ```shell
+      # Check Agent Control pods
       kubectl get pods -n newrelic
   ```
+  ```shell
+      # Check pods in the agent namespace, e.g., 'newrelic-agents'
+      kubectl get pods -n newrelic-agents
+  ```
 
 ## Configuration [#configuration]
 
-In `values-newrelic.yaml`, you can configure the installation of multiple monitoring agents. This example shows the options available, including New Relic's infrastructure agent, Fluent Bit logs agent, OpenTelemetry collector agent, and [New Relic Pipeline Control](/docs/new-relic-control/pipeline-control/overview) gateway agent:
+In the `values-newrelic.yaml` file, you can configure you can configure Agent Control to deploy multiple monitoring agents. Here's an example showing the deployment of several agents, including:
+- **Infrastructure:** New Relic's infrastructure agent
+- **Logs:** Fluent Bit logs agent
+- **OpenTelemetry:** The New Relic distribution of the OpenTelemetry Collector
+- **Gateway:** [New Relic Pipeline Control](/docs/new-relic-control/pipeline-control/overview) gateway agent
 
 ```yaml
 agent-control-deployment:
@@ -179,16 +193,23 @@ agent-control-deployment:
                 maxReplicas: 10
                 targetCPUUtilizationPercentage: 70
 ```
+<Callout variant="important">
+  **Important:** For production environments, we strongly recommend using a specific, pinned `chart_version` instead of a wildcard (`*`). This ensures consistent and predictable updates, preventing unexpected behavior or breaking changes.
+</Callout>
 
 ## Uninstall [#uninstall]
 
 <Callout variant="important">
-    Removing a Helm release resource from your Terraform configuration is a destructive action. After you run `terraform apply` following this change, Terraform will uninstall and destroy the related resources in your Kubernetes cluster. This can result in the loss of data and configurations tied to the resources managed by that Helm release. Before proceeding, make sure you fully understand the potential impact on your environment:
+    Removing a Helm release resource from your Terraform configuration is a **destructive action**. When you run `terraform apply` after this change, Terraform will uninstall the chart and destroy **all** the related resources, potentially leading to data loss. Before proceeding, make sure you fully understand the potential impact on your environment:
     - Review all dependencies and services that might be affected.
     - Consider backing up any persistent data or configurations linked to the release.
     - Confirm that removing this release is necessary and fits your infrastructure management strategy.
     Always exercise caution when making significant changes to your infrastructure, and ensure you have proper rollback procedures in place in case something goes wrong.
 </Callout>
 
-- Run `terraform plan`: After removing the Helm release resource block from your configuration, run the `terraform plan` command. This allows you to review the changes Terraform plans to make to your infrastructure. Carefully examine the plan output to ensure that only the intended resources are marked for deletion. This step is essential to verify that no unintended deletions or changes will occur.
-- Run `terraform apply`: If the terraform plan results align with your expectations, proceed by running the `terraform apply` command. This will implement the planned changes, effectively removing the specified Helm release from your environment. Confirm the execution when prompted to complete the uninstallation process.
+### To uninstall Agent Control:
+1. **Remove the `helm_release` resource block** for `newrelic_agent_control` from your `main.tf` file.
+2. **Run `terraform plan`** to review the changes. Carefully examine the plan output to ensure that only the intended resources are marked for deletion.
+3. **Run `terraform apply`** and confirm the execution to uninstall the release. This will implement the planned changes, effectively removing the specified Helm release from your environment. 
+
+Confirm the execution when prompted to complete the uninstallation process.

src/content/docs/logs/log-collectors/log-collector-management.mdx

@@ -23,14 +23,17 @@ This solution is useful for DevOps teams, system administrators, and IT operatio
 
 - **Troubleshooting:** You can troubleshoot and fix configuration issues with your log collectors using the Fluent Bit entity UI, which helps identify and resolve problems.
 
-- **Configuration and remote deployment:** With New Relic Control, you can centrally manage Fluent Bit configurations, update them, and deploy changes remotely.
-
+- **Centralized configuration and remote deployment:** With **New Relic Control**, you can centrally manage Fluent Bit configurations, update them, and deploy changes across your entire fleet remotely. This is the core benefit of the **Agent Control** solution.
    <img
      title="Fluent Bit entity dashboard"
      alt="Fluent Bit entity dashboard"
      src="/images/fluent-bit-dashboard.webp"
    />
 
+<Callout variant="tip">
+  While Agent Control solution is designed to support both containerized and on-premise environments, **Agent Control is currently supporting Kubernetes environments**.
+</Callout>
+
 ## Manage your Fluent Bit collector for Kubernetes clusters
 The log collector lifecycle management solution currently provides support for Kubernetes environments. It enables you to:
 
@@ -47,22 +50,19 @@ Before you install and configure Fluent Bit for logging with New Relic, ensure y
 
 <Callout variant="important">
   You can also manage Fluent Bit via New Relic Control.  For information, see [Fleet Control](/docs/new-relic-control/fleet-control/overview).
+  Agent Control currently only supports **Kubernetes**.
 </Callout>
 
 For more information on these requirements, refer to [Forward your logs to New Relic](/docs/logs/forward-logs/enable-log-management-new-relic).<br/>
 For information on New Relic Control setup, see [Getting started with New Relic Control](/docs/new-relic-control/getting-started).
 
 ### Set up
-To install the Fluent Bit agent in Kubernetes clusters:
-- Install the [New Relic Kubernetes integration](/install/kubernetes/). This integration includes the Kubernetes plugin for logs.
-- Use the configuration options available in the [newrelic-logging repository](https://github.com/newrelic/helm-charts/tree/master/charts/newrelic-logging#configuration) during the [guided install](/install/kubernetes/).
+You have two primary options for setting up Fluent Bit in your Kubernetes clusters. We recommend using New Relic Control for centralized, fleet-wide management.
 
-For details, refer to [Enable Kubernetes for log management](/docs/logs/forward-logs/kubernetes-plugin-log-forwarding/#enable-process).
+#### Option 1 (Recommended): Install Fluent Bit with New Relic Control
 
-## Install Fluent Bit with Fleet Control
-If you're starting with Fleet Control, you'll set up your agent control configuration first. This process includes installing the Fluent Bit agent and other essential components. 
-
-To use Fluent Bit with Agent Control, enable log forwarding as part of the Agent Control installation, as shown in the sample configuration:
+For an installation that's fully managed by Agent Control, enable log forwarding as part of your New Relic Control guided installation. This process installs the Fluent Bit agent and other essential components and registers the agent with your fleet.
+To use Fluent Bit with Agent Control, enable log forwarding as part of the Agent Control installation, as shown in the sample configuration below.
 
 <CollapserGroup>
   <Collapser
@@ -122,6 +122,13 @@ Remember to uncomment the necessary configurations and replace placeholders such
   Specify an explicit chart version to ensure consistency and reliability across deployments.
 </Callout>
 
+#### Option 2: Install with the Kubernetes integration
+
+If you prefer to install Fluent Bit without using Agent Control, follow these steps:
+
+- Install the [New Relic Kubernetes integration](/install/kubernetes/). This integration includes the Kubernetes plugin for logs.
+- Use the configuration options available in the [newrelic-logging repository](https://github.com/newrelic/helm-charts/tree/master/charts/newrelic-logging#configuration) during the [guided install](/install/kubernetes/).
+
 
 ## Manage and deploy configuration via Fleet Control
 To add a new or edit an existing Fluent Bit configuration, use [Fleet Control](/docs/new-relic-control/fleet-control/overview). The high-level tasks to manage and deploy a configuration are:
@@ -165,7 +172,12 @@ Effective performance monitoring of the Fluent Bit agent is crucial for log mana
 - **Memory buffer utilization:** Helps identify resource constraints affecting log processing. It includes buffer usage, instances of overflows, queue length, and overall process and container memory utilization.
 - **Container events and crash loop backoffs:** Alerts to abnormal conditions or failures in log pods, including errors, dropped records, and retries. These insights help in identifying and addressing issues that may disrupt log processing.
 
-You can monitor the health and performance of your Fluent Bit agent on the Fluent Bit entity dashboard. Here’s how you can access it:
+You can monitor the health and performance of your Fluent Bit agent on the Fluent Bit entity dashboard. For agents managed by New Relic Control, we recommend using the following method.
+
+#### Via Fleet (Recommended for managed agents)
+1. In New Relic Control, open **Fleets**.
+2. Identify and select the fleet that has the Fluent Bit instrumentation.
+3. On the Agents tab, select the Fluent Bit agent.
 
 #### Via Integrations & Agents
 1. Open the **Installed** tab. You’ll see the list of agents and integrations currently installed.
@@ -176,11 +188,6 @@ You can monitor the health and performance of your Fluent Bit agent on the Fluen
 1. Find the agent that you want to monitor under the Fluent Bit - Kubernetes group.
 2. Select the agent.
 
-### Via Fleet
-1. In New Relic Control, open **Fleets**.
-2. Identify and select the fleet that has the Fluent Bit instrumentation.
-3. On the Agents tab, select the Fluent Bit agent.
-
 ## Example Use case: Log flow efficiency
 Imagine that the logs in your Kubernetes cluster are not arriving at New Relic at the usual rate. Your typical log flow might be around 150,000 logs per minute, but current observations suggest a noticeable drop. Here’s how you can address this situation, leveraging New Relic Control and Fluent Bit monitoring tools to diagnose and resolve the issue.