diff --git a/content/en/integrations/guide/aws-agent-installation.md b/content/en/integrations/guide/aws-agent-installation.md new file mode 100644 index 00000000000..f0605bc1b26 --- /dev/null +++ b/content/en/integrations/guide/aws-agent-installation.md @@ -0,0 +1,111 @@ +--- +title: Install the Datadog Agent through the AWS Integration +description: "Deploy the Datadog Agent to your EC2 and EKS resources directly from the AWS integration" +private: true # TODO(DOCS-14545): remove at v1 rollout to publish; also add the nextlink entry in integrations/guide/_index.md at that time +further_reading: +- link: "https://docs.datadoghq.com/integrations/amazon_web_services/" + tag: "Documentation" + text: "AWS Integration" +- link: "https://docs.datadoghq.com/integrations/guide/aws-manual-setup/" + tag: "Documentation" + text: "AWS Manual Setup Guide" +- link: "https://docs.datadoghq.com/agent/fleet_automation/" + tag: "Documentation" + text: "Fleet Automation" +- link: "https://docs.datadoghq.com/agent/configuration/" + tag: "Documentation" + text: "Basic Agent Usage" +--- + +## Overview + +The [AWS integration][1] collects metrics, events, and logs from Amazon CloudWatch without installing anything on your hosts. Installing the Datadog Agent adds telemetry from inside your AWS workloads that CloudWatch alone can't provide, including host-level metrics, distributed traces (APM), live processes, and detailed logs. + +You can deploy the Datadog Agent to your Amazon EC2 and Amazon EKS resources directly from Datadog, without connecting to each host or running per-host scripts. Enable Agent installation while you set up the AWS integration, or at any time afterward. + +## Prerequisites + +Before you begin, make sure of the following: + +- You can approve a CloudFormation stack in the target AWS account. Installation deploys a CloudFormation stack in your account, so you (or a teammate) need permission to review and create it. +- Your Datadog IAM role has the permissions described in the following section. + +The following resource-specific requirements also apply: + +- **Amazon EC2**: The [AWS Systems Manager (SSM) Agent][2] must already be present on the target instances. Datadog installs the Agent through SSM and can't install the SSM Agent for you, so instances built from custom AMIs without the SSM Agent are not eligible. Datadog flags these instances so you can address them. +- **Amazon EKS**: + +## Required AWS permissions + +{{% aws-agent-installation %}} + +## How it works + +When you install the Agent through the AWS integration, you choose the resources, and Datadog handles the deployment inside your own account: + +1. Select the EC2 instances and EKS clusters where you want the Agent installed, or opt in to all eligible resources. +1. Datadog deploys the Agent to those resources. On EC2, Datadog installs the Agent through AWS Systems Manager. If an instance is missing the IAM configuration required to install the Agent, Datadog sets it up automatically. +1. Datadog maintains the installation on the resources you selected. + +You approve one CloudFormation stack, one time, during initial setup. After that, installations run automatically from Datadog, with no new CloudFormation template to launch for each installation. + +{{< img src="integrations/amazon_web_services/aws-agent-installation-how-it-works.png" alt="Flow of installing the Datadog Agent through the AWS integration. In Datadog: connect your AWS account, Datadog discovers eligible EC2 and EKS resources, select resources or opt in to all eligible, and approve the CloudFormation stack once. In your AWS account: the CloudFormation stack creates an install role, the Agent is installed through SSM with IAM remediated if needed, and Agents come online and report to Datadog. Back in Datadog, view the installed Agents." style="width:70%;" >}} + +## Install the Agent + +Start Agent installation as part of AWS integration setup, or from the AWS integration page at any time. + + + +1. In Datadog, open the [AWS integration page][4]. +1. Enable Agent installation. During initial CloudFormation setup, this appears as a toggle alongside log and resource collection. +1. Opt in to all eligible resources, or select specific EC2 instances and EKS clusters from the resource list. +1. Review the generated CloudFormation stack, then continue to AWS and create it. Datadog prompts you for this only once. +1. Return to Datadog. The installation proceeds automatically, and Datadog reports progress as Agents come online. + + + +## Verify the installation + +After the installation completes: + +- The newly installed Agents appear in the [Infrastructure List][5] and on the host map. +- Fleet Automation lists the same Agents in the Fleet View. + + + +## Manage installed Agents + +Use the AWS Install Agents page in Fleet Automation to manage the Agents you've installed through the AWS integration. + +From this page, you can: + +- View the installed Agents and their status. +- Install the Agent on new resources in your AWS environment. +- Uninstall Agents from resources you no longer want to monitor. + +Manage Agent configuration and version upgrades through [Fleet Automation][6]. + +## Troubleshooting + +### The SSM Agent is not present on an EC2 instance + +Agent installation on EC2 relies on the AWS Systems Manager (SSM) Agent, which Datadog can't install for you. Datadog flags any instance that lacks it as ineligible, including those built from custom AMIs. Install the SSM Agent on the instance, then retry. See [Working with SSM Agent][2] in the AWS documentation. + +### A permission or IAM error occurs + +If installation can't complete because of missing permissions, Datadog shows a notification with a link to the relevant CloudFormation resource so you can resolve it. Confirm that the permissions in the [Required AWS permissions](#required-aws-permissions) section are in place. + +### EKS installation is delayed or fails on a private cluster + + + +## Further reading + +{{< partial name="whats-next/whats-next.html" >}} + +[1]: https://docs.datadoghq.com/integrations/amazon_web_services/ +[2]: https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent.html +[4]: https://app.datadoghq.com/integrations/amazon-web-services +[5]: https://app.datadoghq.com/infrastructure +[6]: https://docs.datadoghq.com/agent/fleet_automation/ diff --git a/layouts/shortcodes/aws-agent-installation.en.md b/layouts/shortcodes/aws-agent-installation.en.md new file mode 100644 index 00000000000..473116e93c4 --- /dev/null +++ b/layouts/shortcodes/aws-agent-installation.en.md @@ -0,0 +1,37 @@ +Agent installation requires permissions beyond the base [AWS integration IAM policy](https://docs.datadoghq.com/integrations/amazon_web_services/#aws-iam-permissions). These permissions let Datadog: + +- Store your Datadog API key (AWS Secrets Manager). +- Create and attach the IAM role used to install the Agent (IAM). +- Install the Agent on your EC2 instances (AWS Systems Manager). +- Maintain the Agent's presence (Amazon EventBridge). +- Provision supporting infrastructure for EKS installations (AWS Lambda). + +
All write actions run inside your own AWS account through the role created by the CloudFormation stack. Datadog holds no persistent write credentials to your account.
+ +Add the following permissions to your AWS integration IAM policy: + + + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "DatadogAgentInstall", + "Effect": "Allow", + "Action": [ + "secretsmanager:CreateSecret", + "secretsmanager:PutSecretValue", + "iam:CreateRole", + "iam:AttachRolePolicy", + "iam:PassRole", + "ssm:SendCommand", + "ssm:ListCommands", + "events:PutRule", + "events:PutTargets" + ], + "Resource": "*" + } + ] +} +``` diff --git a/static/images/integrations/amazon_web_services/aws-agent-installation-how-it-works.png b/static/images/integrations/amazon_web_services/aws-agent-installation-how-it-works.png new file mode 100644 index 00000000000..5b53e7c3862 Binary files /dev/null and b/static/images/integrations/amazon_web_services/aws-agent-installation-how-it-works.png differ