diff --git a/README.md b/README.md index bf8af10a3..ba3e74a5e 100644 --- a/README.md +++ b/README.md @@ -55,6 +55,16 @@ page. The latest New Relic CLI documentation is available in the repository's [docs](https://github.com/newrelic/newrelic-cli/blob/main/docs/cli/newrelic.md) directory. +### Guided Install: Scope and Usage + +The `newrelic install` command provides automated installation of New Relic agents and integrations. + +**Important:** This command is designed for **initial installations on new hosts**. When run on a system with existing New Relic agents, it will reset configurations to defaults as part of ensuring a clean installation. + +For upgrading existing agents while preserving custom configurations, use the [manual upgrade procedures](https://docs.newrelic.com/docs/infrastructure/install-infrastructure-agent/update-or-uninstall/update-infrastructure-agent/) documented for each agent type. + +See the [Install Guide](docs/INSTALL_GUIDE.md) for detailed information about when to use guided install versus manual upgrades. + ## Installation & Upgrades Installation options are available for various platforms. If you're running an older version of the CLI you can use these commands to update to the latest version. @@ -321,9 +331,8 @@ New Relic hosts and moderates an online forum where you can interact with New Re - [Roadmap](https://newrelic.github.io/developer-toolkit/roadmap/) - As part of the Developer Toolkit, the roadmap for this project follows the same RFC process - [Issues or Enhancement Requests](https://github.com/newrelic/newrelic-cli/issues) - Issues and enhancement requests can be submitted in the Issues tab of this repository. Please search for and review the existing open issues before submitting a new issue. - [Contributors Guide](CONTRIBUTING.md) - Contributions are welcome (and if you submit a Enhancement Request, expect to be invited to contribute it yourself :grin:). -- [Community discussion board](https://discuss.newrelic.com/c/build-on-new-relic/developer-toolkit) - Like all official New Relic open source projects, there's a related Community topic in the New Relic Explorers Hub. -Please do not report issues with the CLI to New Relic Global Technical Support. Instead, visit the [`Explorers Hub`](https://discuss.newrelic.com/c/build-on-new-relic) for troubleshooting and best-practices. +Please do not report issues with the CLI to New Relic Global Technical Support. Instead, submit issues and questions through [GitHub Issues](https://github.com/newrelic/newrelic-cli/issues) for community support and troubleshooting. ## Issues / Enhancement Requests diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md index 830ccdb28..741e81784 100644 --- a/docs/GETTING_STARTED.md +++ b/docs/GETTING_STARTED.md @@ -23,6 +23,10 @@ docker run -i --rm -e NEW_RELIC_API_KEY newrelic/cli apm application search --na Binary releases are available on [GitHub][releases] as well and installed anywhere in the environment `$PATH` for the user. +### Guided Install + +The CLI includes a `newrelic install` command for automated agent installation. This command is designed for initial installations on new hosts. For upgrading existing agents while preserving custom configurations, see the [Install Guide](INSTALL_GUIDE.md) for guidance on when to use guided install versus manual upgrades. + ### Environment Setup You will need a [Personal API Key][api_key] in order to make full use of this @@ -247,8 +251,7 @@ Custom events may take a moment to appear in query results while they are being ### Want more? -If you'd like to engage with other community members, visit our -[discuss][discuss] page. We welcome feature requests or bug reports on GitHub. +We welcome feature requests or bug reports on [GitHub Issues](https://github.com/newrelic/newrelic-cli/issues). We also love Pull Requests. [homebrew]: https://brew.sh/ @@ -260,5 +263,3 @@ We also love Pull Requests. [api_key]: https://docs.newrelic.com/docs/apis/get-started/intro-apis/types-new-relic-api-keys#personal-api-key [jq]: https://stedolan.github.io/jq/ - -[discuss]: https://discuss.newrelic.com/c/build-on-new-relic/developer-toolkit diff --git a/docs/INSTALL_GUIDE.md b/docs/INSTALL_GUIDE.md new file mode 100644 index 000000000..fb7aa9ed0 --- /dev/null +++ b/docs/INSTALL_GUIDE.md @@ -0,0 +1,111 @@ +# New Relic CLI Guided Install Guide + +## Overview + +The `newrelic install` command provides an automated, guided installation experience for New Relic agents and integrations. This guide helps you understand when to use guided install and when to use alternative methods. + +## Intended Use + +### Guided Install is Designed For + +The CLI-based guided installation provides a simple, single-command experience for **initial installation on new hosts**: + +- Customers who want an easy, automated installation process +- Standard agent deployments with default configurations +- Embedding in automated deployment scripts to ensure new servers are monitored from day one +- Integration with configuration management tools (Ansible, Puppet, Chef) +- Scenarios where a quick, consistent installation is preferred + +Advanced users who require fine-grained control over installation settings, specific version pinning, or custom configuration during installation may prefer manual installation procedures. + +### How Guided Install Works + +When you run `newrelic install`, the command: + +1. Detects your system configuration and running services +2. Recommends appropriate New Relic agents and integrations +3. Installs agents with default configuration settings +4. Validates that agents are reporting data successfully + +To ensure a consistent installation experience, the command configures agents with standard default settings. This approach works well for new installations where no prior configuration exists. + +## Upgrading Existing Agents + +If you have existing New Relic agents with custom configurations that you want to preserve, use the manual upgrade procedures instead: + +### Infrastructure Agent Upgrades + +For detailed upgrade instructions specific to your operating system, see the New Relic documentation: + +**Documentation:** [Update Infrastructure Agent](https://docs.newrelic.com/docs/infrastructure/install-infrastructure-agent/update-or-uninstall/update-infrastructure-agent/) + +### APM Agent Upgrades + +Each APM agent has specific upgrade procedures that preserve your configurations. See the New Relic documentation for language-specific upgrade instructions: + +**Documentation:** [APM Agent Updates](https://docs.newrelic.com/docs/apm/) + +## Configuration Considerations + +### What Happens to Existing Configurations + +If you run `newrelic install` on a system with existing New Relic agents: + +- Agent configuration files are set to default values +- Custom settings (log paths, custom attributes, labels) are not preserved +- Integration configurations are reset to defaults + +This behavior ensures a clean, consistent installation but may not be suitable for systems with custom configurations you want to keep. + +### Backing Up Configurations + +If you plan to use guided install on a system with existing agents, consider backing up your configuration files first: + +**Linux:** +```bash +# Back up main config file +sudo cp /etc/newrelic-infra.yml /etc/newrelic-infra.yml.backup + +# Back up integrations directory +sudo cp -r /etc/newrelic-infra /etc/newrelic-infra.backup +``` + +**Windows:** +```powershell +Copy-Item -Path "C:\Program Files\New Relic\newrelic-infra" -Destination "C:\Program Files\New Relic\newrelic-infra.backup" -Recurse +``` + +## Frequently Asked Questions + +### Can I use guided install to upgrade my existing agents? + +While the command will run successfully, it's designed for new installations. For upgrades that preserve your custom configurations, we recommend using the manual upgrade procedures for your specific agent type. + +### Will my telemetry data be affected? + +No. Guided install only affects local agent configuration files. Your historical data in New Relic remains unchanged. + +### Can I customize the installation? + +The guided install uses standard default configurations. For custom setups, you can either: +1. Use guided install and then manually edit configuration files afterward +2. Perform a manual installation following agent-specific documentation + +### What if I need help? + +- **Documentation:** [New Relic Docs](https://docs.newrelic.com/) +- **Issues and Questions:** [GitHub Issues](https://github.com/newrelic/newrelic-cli/issues) +- **General Support:** [New Relic Support](https://support.newrelic.com/) + +## Command Reference + +For complete command options, run: + +```bash +newrelic install --help +``` + +See also: +- [CLI Documentation](newrelic.md) +- [Getting Started Guide](GETTING_STARTED.md) +- [New Relic Infrastructure Agent Documentation](https://docs.newrelic.com/docs/infrastructure/) diff --git a/docs/cli/newrelic_install.md b/docs/cli/newrelic_install.md index 041708837..7587736a2 100644 --- a/docs/cli/newrelic_install.md +++ b/docs/cli/newrelic_install.md @@ -2,6 +2,12 @@ Install New Relic. +### Important: Intended Use + +The `newrelic install` command is designed for **initial installation on new hosts**. It provides an automated, guided installation experience that configures New Relic agents with default settings. + +**Note for existing installations:** Running this command on a host with existing New Relic agents will reset agent configurations to defaults. If you need to upgrade agents while preserving custom configurations, use the [manual upgrade procedures](https://docs.newrelic.com/docs/infrastructure/install-infrastructure-agent/update-or-uninstall/update-infrastructure-agent/) instead. + ``` newrelic install [flags] ```