Skip to content

Commit

Permalink
Merge pull request #1576 from pjanotti/patch-3
Browse files Browse the repository at this point in the history 
Replace ecs-metadata with awsecscontainermetrics
  • Loading branch information
@aurbiztondo-splunk
aurbiztondo-splunk authored Oct 23, 2024
2 parents 1b39708 + 1ce55f6 commit 19e49ed
Showing 1 changed file with 35 additions and 49 deletions.
84 changes: 35 additions & 49 deletions gdi/opentelemetry/deployments/deployments-ecs-ec2.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@ Deploy the Collector with Amazon ECS EC2
********************************************************

.. meta::
:description: Deploy the Splunk Observability Cloud OpenTelemetry Collector as a Daemon service in an Amazon ECS EC2 cluster.
:description: Deploy the Splunk Observability Cloud OpenTelemetry Collector as a Sidecar in an Amazon ECS EC2 cluster.

Use the guided setup to deploy the Collector as a Daemon service in an Amazon ECS EC2 cluster. The guided setup provides a JSON task definition for the Collector.
Use the guided setup to deploy the Collector as a Sidecar in an Amazon ECS EC2 cluster. The guided setup provides a JSON task definition for the Collector.

Choose one of the following Collector configuration options:

Expand All @@ -28,76 +28,43 @@ Getting started

The following sections describe how to create a task definition and launch the Collector. A task definition is required to run Docker containers in Amazon ECS. After creating the task definition, you need to launch the Collector.

Create a task definition
Add the Collector as a Sidecar
---------------------------------
.. note::

Knowledge of Amazon ECS using launch type EC2 is assumed. See :new-page:`Getting started with the classic console using Amazon EC2 <https://docs.aws.amazon.com/AmazonECS/latest/developerguide/getting-started-ecs-ec2.html>` for further reading.

Creating the task definition requires using release v0.34.1 or newer (which corresponds to image tag 0.34.1 and newer) of the Collector. See the :new-page:`image repository <https://quay.io/repository/signalfx/splunk-otel-collector?tab=tags>` to download the latest image.
.. note:: To use this option you need to be familiar with Amazon ECS EC2 launch type. See :new-page:`Getting started with the classic console using Amazon EC2 <https://docs.aws.amazon.com/AmazonECS/latest/developerguide/getting-started-ecs-ec2.html>` for further reading.

To create the task definition:
Open the ECS task definition to which the Collector Sidecar is going to be added:

1. Locate the task definition for the Collector from the :new-page:`repository <https://github.com/signalfx/splunk-otel-collector/blob/main/deployments/ecs/ec2/splunk-otel-collector.json>`.
2. Replace ``MY_SPLUNK_ACCESS_TOKEN`` and ``MY_SPLUNK_REALM`` with valid values. You should pin the image version to a specific version instead of ``latest`` to avoid upgrade issues.
3. Create a task definition of EC2 launch type. See :new-page:`Creating a task definition using the new console <https://docs.aws.amazon.com/AmazonECS/latest/developerguide/create-task-definition.html>` for the instructions. The supplied task definition is a minimal definition. See :new-page:`Task definition parameters <https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html>` for additional configuration options.
2. Merge the definitions of the Collector with the existing ECS task definition.
3. Replace ``MY_SPLUNK_ACCESS_TOKEN`` and ``MY_SPLUNK_REALM`` with valid values. You can pin the image version to a specific version instead of ``latest`` if you want to avoid automatic upgrades.

The Collector is configured to use the default configuration file ``/etc/otel/collector/ecs_ec2_config.yaml``. The Collector image Dockerfile is available at :new-page:`Dockerfile <https://github.com/signalfx/splunk-otel-collector/blob/main/cmd/otelcol/Dockerfile>` and the contents of the default configuration file can be seen at :new-page:`ECS EC2 configuration <https://github.com/signalfx/splunk-otel-collector/blob/main/cmd/otelcol/config/collector/ecs_ec2_config.yaml>`.

.. note::

You do not need the ``smartagent/ecs-metadata`` metrics receiver in the default configuration file if all you want is tracing. You can take the default configuration, remove the receiver, then use the configuration in a custom configuration following the directions in :ref:`ecs-ec2-custom-config`.

The configured network mode for the task is ``host``. This means that task metadata endpoint version 2 used by the ``smartagent/ecs-metadata`` receiver is not activated by default. See :new-page:`task metadata endpoint <https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-metadata-endpoint.html>` to determine if task metadata endpoint version 3 is activated by default for your task. If this version is activated, then add the following to the environment list in the task definition:
Notes:

.. code-block:: none
* You do not need the ``awsecscontainermetrics`` receiver in the default configuration file if all you want is tracing. You can take the default configuration, remove the receiver, then use the configuration in a custom configuration following the directions in :ref:`ecs-ec2-custom-config`.

{
"name": "ECS_TASK_METADATA_ENDPOINT",
"value": "${ECS_CONTAINER_METADATA_URI}/task"
},
{
"name": "ECS_TASK_STATS_ENDPOINT",
"value": "${ECS_CONTAINER_METADATA_URI}/task/stats"
}
* To exclude metrics assign them as a stringified array to environment variable ``METRICS_TO_EXCLUDE``.

Assign a stringified array of metrics you want excluded to environment variable ``METRICS_TO_EXCLUDE``. You can set the memory limit for the ``memory_limiter`` processor using environment variable ``SPLUNK_MEMORY_LIMIT_MIB``. The default memory limit is 512 MiB.

Launch the Collector
=============================
The Collector is designed to be run as a Daemon service in an EC2 ECS cluster. To create a Collector service from the Amazon ECS console:

#. Go to your cluster in the console.
#. Select :guilabel:`Services`.
#. Select :guilabel:`Create`.
#. Select the following options:
#. Launch Type: EC2
#. Task Definition (Family): splunk-otel-collector
#. Task Definition (Revision): 1 (or whatever the latest is in your case)
#. Service Name: splunk-otel-collector
#. Service type: DAEMON
#. Leave everything else at default.
#. Select :guilabel:`Next step`.
#. Leave everything on this next page at their defaults and select :guilabel:`Next step`.
#. Leave everything on this next page at their defaults and select :guilabel:`Next step`.
#. Select :guilabel:`Create Service` to deploy the Collector onto each node in the ECS cluster. You should see infrastructure and docker metrics flowing soon.
* You can set the memory limit for the ``memory_limiter`` processor using environment variable ``SPLUNK_MEMORY_LIMIT_MIB``. The default memory limit is 512 MiB.

.. _ecs-ec2-custom-config:

Use a custom configuration
==============================

To use a custom configuration file, replace the value of the ``SPLUNK_CONFIG`` environment variable with the file path of the custom configuration file in the Collector task definition.

Alternatively, you can specify the custom configuration YAML directly using the ``SPLUNK_CONFIG_YAML`` environment variable, as described in :ref:`ecs-observer-config`.

.. _ecs-observer-config:

``ecs_observer`` configuration
Configure ``ecs_observer``
--------------------------------
Use extension Amazon Elastic Container Service Observer (``ecs_observer``) in your custom configuration to discover metrics targets in running tasks, filtered by service names, task definitions, and container labels. ``ecs_observer`` is currently limited to Prometheus targets and requires the read-only permissions below. You can add the permissions to the task role by adding them to a customer-managed policy that is attached to the task role.

.. code-block:: yaml
Use extension Amazon Elastic Container Service Observer (``ecs_observer``) in your custom configuration to discover metrics targets in running tasks, filtered by service names, task definitions, and container labels. ``ecs_observer`` is currently limited to Prometheus targets and requires the read-only permissions below. The Collector should be configured to run as an ECS Daemon. You can add the permissions to the task role by adding them to a customer-managed policy that is attached to the task role.

.. code-block:: yaml
ecs:List*
ecs:Describe*
Expand All @@ -108,7 +75,6 @@ The results are written to ``/etc/ecs_sd_targets.yaml``. The ``prometheus`` rece

.. code-block:: yaml
extensions:
ecs_observer:
refresh_interval: 10s
Expand Down Expand Up @@ -147,6 +113,26 @@ The results are written to ``/etc/ecs_sd_targets.yaml``. The ``prometheus`` rece
.. _aws-parameter-store:

Launch the Collector as a Daemon
--------------------------------------------

To launch the Collector from the Amazon ECS console:

#. Go to your cluster in the console.
#. Select :guilabel:`Services`.
#. Select :guilabel:`Create`.
#. Select the following options:
#. Launch Type: EC2
#. Task Definition (Family): splunk-otel-collector
#. Task Definition (Revision): 1 (or whatever the latest is in your case)
#. Service Name: splunk-otel-collector
#. Service type: DAEMON
#. Leave everything else at default.
#. Select :guilabel:`Next step`.
#. Leave everything on this next page at their defaults and select :guilabel:`Next step`.
#. Leave everything on this next page at their defaults and select :guilabel:`Next step`.
#. Select :guilabel:`Create Service` to deploy the Collector onto each node in the ECS cluster. You should see infrastructure and docker metrics flowing soon.

Use the AWS Parameter Store
----------------------------

Expand Down

0 comments on commit 19e49ed

Please sign in to comment.