Manage the Amazon Distro for OpenTelemetry Operator - Amazon EKS
Install the ADOT OperatorUpdate the ADOT OperatorRemove the ADOT Operator
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Manage the Amazon Distro for OpenTelemetry Operator

The Amazon Distro for OpenTelemetry (ADOT) Operator is available as an Amazon EKS add-on. After installing the ADOT Operator, you can configure the ADOT Collector to specify the deployment type and the service that will receive your application metric or trace data. This topic describes how to manage the ADOT add-on.

To install the ADOT Collector, see Deploy the Amazon Distro for OpenTelemetry Collector. Alternatively, with the advanced configuration feature of Amazon EKS add-ons, you can install the ADOT Collector during add-on creation or add-on updates. For more information, see Deploy the Amazon Distro for OpenTelemetry Collector using advanced configuration.

Install the Amazon Distro for OpenTelemetry (ADOT) Operator

Installing the ADOT add-on includes the ADOT Operator, which in turn deploys the ADOT Collector. The ADOT Operator is a custom controller which introduces a new object type called the OpenTelemetryCollector through CustomResourceDefinition (CRD). When the ADOT Operator detects the presence of the OpenTelemetryCollector resource, then it installs the ADOT Collector.

Prerequisites

  • You have met the ADOT prerequisites.

  • kubectl is installed.

  • Update your kubeconfig if necessary using the following command.

    aws eks update-kubeconfig --name my-cluster --region region-code

  • eksctl is installed.

  • Version 2.12.3 or later or 1.27.160 or later of the Amazon CLI installed and configured on your device or Amazon CloudShell. You can check your current version with aws --version | cut -d / -f2 | cut -d ' ' -f1. Package managers such yum, apt-get, or Homebrew for macOS are often several versions behind the latest version of the Amazon CLI. To install the latest version, see Installing, updating, and uninstalling the Amazon CLI and Quick configuration with aws configure in the Amazon Command Line Interface User Guide. The Amazon CLI version installed in the Amazon CloudShell may also be several versions behind the latest version. To update it, see Installing Amazon CLI to your home directory in the Amazon CloudShell User Guide.

  • An existing Amazon EKS cluster.

  • An existing Amazon EKS service IAM role. If you don't have the role, you can follow Create an IAM role to create one.

Amazon Web Services Management Console

Install the ADOT Amazon EKS add-on to your Amazon EKS cluster using the following steps:

  1. Open the Amazon EKS console at https://console.amazonaws.cn/eks/home#/clusters.

  2. In the left pane, select Clusters, and then select the name of your cluster on the Clusters page.

  3. Choose the Add-ons tab.

  4. Choose Get more add-ons.

  5. On the Select add-ons page, do the following:

    1. In the Amazon EKS-addons section, select the Amazon Distro for OpenTelemetry check box.

    2. Choose Next.

  6. On the Configure selected add-ons settings page, do the following:

    1. The default version will be selected in the Version drop-down. Select the Version you'd like to use.

    2. (Optional) If deploying an ADOT Collector, expand Optional configuration settings and provide the Configuration values that match your use case for Collector deployment. The Add-on configuration schema provides the available options for your configuration values.

    3. If a service account is already created in the cluster without an IAM role, expand the Optional configuration settings and select Override for the Conflict resolution method.

    4. Choose Next.

  7. On the Review and add page, choose Create. After the add-on installation is complete, you see your installed add-on.

Amazon CLI

  1. Install the ADOT Amazon EKS add-on to your Amazon EKS cluster. Optionally, the --configuration-values flag can be added to deploy an ADOT Collector during add-on installation. You may also configure other available values with this flag.

    aws eks create-addon --addon-name adot --cluster-name my-cluster --configuration-values my-configuration-values

    The status field value will be CREATING until complete.

  2. Verify that ADOT is installed and running.

    aws eks describe-addon --addon-name adot --cluster-name my-cluster

    You'll see "status": "ACTIVE" when creation is complete.

Update the Amazon Distro for OpenTelemetry (ADOT) Operator

Amazon EKS does not automatically update ADOT on your cluster. You must initiate the update and then Amazon EKS updates the Amazon EKS add-on for you.

To update the ADOT Amazon EKS add-on using the Amazon CLI

  1. Check the current version of your ADOT add-on. Replace my-cluster with your cluster name.

    aws eks describe-addon --cluster-name my-cluster --addon-name adot --query "addon.addonVersion" --output text

  2. Determine the ADOT versions are available that are supported by your cluster's version.

    aws eks describe-addon-versions --addon-name adot --kubernetes-version 1.23 \
    --query "addons[].addonVersions[].[addonVersion, compatibilities[].defaultVersion]" --output text

    An example output is as follows.

    v0.58.0-eksbuild.1
True
v0.56.0-eksbuild.2
False

    The version with True underneath is the default version deployed when the add-on is created. The version deployed when the add-on is created might not be the latest available version. In the previous output, the latest version is deployed when the add-on is created.

  3. Update the ADOT version. Replace my-cluster with the name of your cluster and v0.58.0-eksbuild.1 with the desired version. Optionally, the --configuration-values flag can be added to deploy an ADOT Collector during add-on installation. You may also configure other available values with this flag.

    aws eks update-addon --cluster-name my-cluster --addon-name adot --addon-version v0.58.0-eksbuild.1 --resolve-conflicts PRESERVE --configuration-values my-configuration-values

    The PRESERVE option preserves any custom settings that you've set for the add-on. For more information about other options for this setting, see update-addon in the Amazon EKS Command Line Reference. For more information about Amazon EKS add-on configuration management, see Kubernetes field management.

Remove the Amazon Distro for OpenTelemetry (ADOT) Operator

  • You must delete the ADOT Collector resource separately from the ADOT Collector. In this command, specify the YAML file that you used to deploy the ADOT Collector:

    kubectl delete -f collector-config-(amp|cloudwatch|xray|advanced).yaml

  • You can remove the ADOT Operator through either the Amazon CLI or eksctl. If you remove the ADOT Operator, you must follow the installation instructions again to reinstall:

    CLI

    aws eks delete-addon --addon-name adot --cluster-name my-cluster

    eksctl

    eksctl delete addon --cluster my-cluster --name adot