---
title: Install infrastructure agent as a container
source: https://docs.newrelic.com/docs/infrastructure/infrastructure-agent/linux-installation/infra-agent-as-container
---

The infrastructure agent for Linux [supports container environments](https://docs.newrelic.com/docs/infrastructure/install-infrastructure-agent/linux-installation/docker-instrumentation-infrastructure) by default. If you're running a container OS or have restrictions that require deploying the agent as a container, you can run a containerized version of our infrastructure agent. This can monitor metrics for the container itself, as well as the underlying host.

Using the [custom (recommended)](#custom-setup) or [basic setup](#simple-setup) allows the infrastructure agent to run inside a container environment. A host can only run one instance of the agent at a time, whether that's the containerized agent or the non-containerized version.

## What you need [#requirements]

The containerized version of the infrastructure agent requires Docker 1.12 or higher.

From version 1.42, the infrastructure agent supports `containerd`, so it can be used in Kubernetes v1.24+, which removed support for Dockershim, or any other `containerd`-based solution. If both the `containerd` and the `dockerd` runtime sockets are available, the infrastructure agent will operate with the `containerd` runtime socket. The container must run on a [Linux distribution and version](https://docs.newrelic.com/docs/infrastructure/install-infrastructure-agent/get-started/compatibility-requirements-infrastructure-agent#operating-systems) supported by the infrastructure agent. The container image is available and supported on AMD64 and ARM64 architectures.

The log forwarder is not included with the containerized agent. We recommend installing the agent on the underlying host which provides all capabilities.

## Custom setup (recommended) [#custom-setup]

The following are basic instructions for creating a custom Docker image on Linux. This allows you to deploy the infrastructure agent as a container that can monitor its underlying host.

Recommendation: Extend the [`newrelic/infrastructure` image](https://hub.docker.com/r/newrelic/infrastructure/) and use your own `newrelic-infra.yml` agent [config file](https://docs.newrelic.com/docs/infrastructure/new-relic-infrastructure/configuration/configure-infrastructure-agent). Once your image is built, you can easily spin up a container without having to provide more launch time configurations. Do not provide secrets using environment variables with Docker.

### Docker CLI

1.  Create the `newrelic-infra.yml` agent [config file](https://docs.newrelic.com/docs/infrastructure/new-relic-infrastructure/configuration/configure-infrastructure-agent) with your New Relic license key. For config option explanations, see [configuration settings](https://docs.newrelic.com/docs/infrastructure/install-configure-infrastructure/configuration/infrastructure-configuration-settings).

    ```yml
    license_key: YOUR_LICENSE_KEY
    ```
2.  Create the `Dockerfile` extending the `newrelic/infrastructure` image, and add your config to `/etc/newrelic-infra.yml`:

    ```dockerfile
    FROM newrelic/infrastructure:latest
    ADD newrelic-infra.yml /etc/newrelic-infra.yml
    ```
3.  Build and tag your image:

    ```bash
    docker build -t YOUR_IMAGE_NAME .
    ```
4.  Run the container from the image you built with the required [required run flags](#required-privileges):

    ```bash
    docker run \
        -d \
        --name newrelic-infra \
        --network=host \
        --cap-add=SYS_PTRACE \
        --privileged \
        --pid=host \
        --cgroupns=host \  # required on cgroup v2
        -v "/:/host:ro" \
        -v "/var/run/docker.sock:/var/run/docker.sock" \
        YOUR_IMAGE_NAME
    ```
5.  For potential next steps, like how to see data in the UI, see [What's next?](https://docs.newrelic.com/docs/infrastructure/install-infrastructure-agent/linux-installation/install-infrastructure-monitoring-agent-linux#what-next)

### Docker Compose

1.  Create a folder to store the configuration files:

    ```bash
    mkdir ~/newrelic-infra-setup
    ```
2.  Change directory to the one you've just created:

    ```bash
    cd ~/newrelic-infra-setup
    ```
3.  Create the `newrelic-infra.yml` agent [config file](https://docs.newrelic.com/docs/infrastructure/new-relic-infrastructure/configuration/configure-infrastructure-agent) with your New Relic license key. For config option explanations, see [configuration settings](https://docs.newrelic.com/docs/infrastructure/install-configure-infrastructure/configuration/infrastructure-configuration-settings).

    ```bash
    echo "license_key: YOUR_LICENSE_KEY" > newrelic-infra.yml
    ```
4.  Create the `newrelic-infra.dockerfile` extending the `newrelic/infrastructure` image, and add your config to `/etc/newrelic-infra.yml`:

    ```bash
    touch newrelic-infra.dockerfile
    ```

    ```bash
    vim newrelic-infra.dockerfile # you can use any text editor
    ```
5.  Put the following content in the file:

    ```dockerfile
    FROM newrelic/infrastructure:latest
    ADD newrelic-infra.yml /etc/newrelic-infra.yml
    ```
6.  Create `docker-compose.yaml`:

    ```bash
    touch docker-compose.yaml
    ```

    ```bash
    vim docker-compose.yaml # you can use any text editor
    ```

    Put following content in the file:

    ```yml
    version: '3'

    services:
      agent:
        container_name: newrelic-infra
        build:
          context: .
          dockerfile: newrelic-infra.dockerfile
        cap_add:
          - SYS_PTRACE
        network_mode: host
        pid: host
        privileged: true
        volumes:
          - "/:/host:ro"
          - "/var/run/docker.sock:/var/run/docker.sock"
        restart: unless-stopped
    ```
7.  Build and start `docker-compose`:

    ```bash
    docker-compose -f docker-compose.yaml up -d
    ```
8.  For potential next steps, like how to see data in the UI, see [What's next?](https://docs.newrelic.com/docs/infrastructure/install-infrastructure-agent/linux-installation/install-infrastructure-monitoring-agent-linux#what-next)

## Basic setup [#simple-setup]

To use the basic setup with a base New Relic infrastructure image:

### Docker CLI [#basic-cli]

1.  Run the container with the [required run flags](#required-privileges):

    ```bash
    docker run \
       -d \
       --name newrelic-infra \
       --network=host \
       --cap-add=SYS_PTRACE \
       --privileged \
       --pid=host \
        --cgroupns=host \ # required on cgroup v2
       -v "/:/host:ro" \
       -v "/var/run/docker.sock:/var/run/docker.sock" \
       -e NRIA_LICENSE_KEY=YOUR_LICENSE_KEY \
       newrelic/infrastructure:latest
    ```
2.  For potential next steps, like how to see data in the UI, see [What's next?](https://docs.newrelic.com/docs/infrastructure/install-infrastructure-agent/linux-installation/install-infrastructure-monitoring-agent-linux#what-next)

### Docker Compose [#basic-compose]

1.  Create `docker-compose.yaml`:

    ```bash
    touch docker-compose.yaml
    ```

    ```bash
    vim docker-compose.yaml # you can use any text editor
    ```

    Put following content in the file:

    ```yml
    version: '3'

    services:
      agent:
        container_name: newrelic-infra
        image: newrelic/infrastructure:latest
        cap_add:
          - SYS_PTRACE
        network_mode: host
        pid: host
        privileged: true
        volumes:
          - "/:/host:ro"
          - "/var/run/docker.sock:/var/run/docker.sock"
        environment:
          NRIA_LICENSE_KEY: "YOUR_LICENSE_KEY"
        restart: unless-stopped
    ```
2.  Build and start `docker-compose`:

    ```bash
    docker-compose -f docker-compose.yaml up -d
    ```
3.  For potential next steps, like how to see data in the UI, see [What's next?](https://docs.newrelic.com/docs/infrastructure/install-infrastructure-agent/linux-installation/install-infrastructure-monitoring-agent-linux#what-next)

## Required container privileges [#required-privileges]

Due to resource isolation from the host and other containers via Linux namespaces, a container has a very restricted view and control of its underlying host's resources by default. Without these extra privileges, the infrastructure agent cannot monitor the host and its containers.

The infrastructure agent collects data about its host using system files and system calls. For more information about how the infrastructure agent collects data, see our documentation about [infrastructure monitoring and security](https://docs.newrelic.com/docs/infrastructure/new-relic-infrastructure/getting-started/infrastructure-security). Required privileges include:

| Privilege                                        | Description                                                                                                                                                                                                                                                                                                                           |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--network=host`                                 | Sets the container's network namespace to the host's network namespace. This allows the agent to collect the network metrics about the host.                                                                                                                                                                                          |
| `-v "/:/host:ro"`                                | Bind mounts the host's root volume to the container. This read-only access to the host's root allows the agent to collect process and storage metrics as well as Inventory data from the host.                                                                                                                                        |
| `--cap-add=SYS_PTRACE`                           | Adds the Linux capability to trace system processes. This allows the agent to gather data about processes running on the host. Read more [here](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities).                                                                                              |
| `--privileged`                                   |                                                                                                                                                                                                                                                                                                                                       |
| `--pid=host`                                     |                                                                                                                                                                                                                                                                                                                                       |
| `--cgroupns=host`                                | Required when using docker on cgroup v2 as it is private by default. This allows the agent to gather container metrics. It is available [since docker engine API v1.41](https://docs.docker.com/engine/reference/commandline/container_create/).
                                                                                     |
| `-v "/var/run/docker.sock:/var/run/docker.sock"` | Bind mounts the host's Docker daemon socket to the container. This allows the agent to connect to the Engine API via the Docker daemon socket to collect the host's container data. If you interact with the `containerd` runtime instead, replace this mount with `/run/containerd/containerd.sock:/run/containerd/containerd.sock`. |

## Next steps after install [#next-steps]

For next steps after install is completed, see [What's next?](https://docs.newrelic.com/docs/infrastructure/install-infrastructure-agent/linux-installation/install-infrastructure-monitoring-agent-linux#what-next)

## Inventory collected [#inventory]

[Inventory](https://docs.newrelic.com/docs/infrastructure/new-relic-infrastructure/infrastructure-ui-pages/infrastructure-inventory-page-search-your-entire-infrastructure) is collected from the infrastructure agent's built-in data collectors. The infrastructure agent collects this data for Linux systems running with containers.

| Category   | Source                                                                                                                                                                                                                                          | Data collected using         |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| `metadata` | `agent_config`                                                                                                                                                                                                                                  | Agent's complete config file |
| `system`   | `uptime -s, /etc/redhat-release, /proc/cpuinfo, /etc/os-release, /proc/sys/kernel/random/boot_id, /proc/sys/kernel/osrelease, /sys/class/dmi/id/product_uuid, /sys/devices/virtual/dmi/id/sys_vendor, /sys/devices/virtual/dmi/id/product_name` |                              |

## Container data [#view]

Once the infrastructure agent is running in a Docker container, it can collect the same [host compute data](https://docs.newrelic.com/docs/infrastructure/infrastructure-ui-pages/infra-hosts-ui-page) and [event data](https://docs.newrelic.com/docs/infrastructure/new-relic-infrastructure/infrastructure-ui-pages/infrastructure-events-page-live-feed-every-config-change) that the infrastructure agent is capable of collecting when running natively on a host. For more information, see our documentation about how to [view your Docker container data](https://docs.newrelic.com/docs/infrastructure/install-infrastructure-agent/linux-installation/docker-instrumentation-infrastructure#find-data).

## Containerized agent image [#view]

The containerized agent image is built from an Alpine base image.

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

This integration is open source software. You can [browse its source code](https://github.com/newrelic/infrastructure-bundle) and send improvements, or create your own fork and build it.