AppD Instrumentation Manager

The AppD Instrumentation Manager provides a streamlined and robust solution for managing AppDynamics agent instrumentation in complex Kubernetes environments. It offers an automated, flexible, and scalable approach to agent injection and removal, designed to simplify operations and enhance reliability for Java, NodeJS, and .Net applications.

🚀 Product Overview

Managing AppDynamics agent instrumentation in complex Kubernetes deployments can be significantly simplified with the right tools. The AppD Instrumentation Manager offers a powerful, automated, and scalable solution for agent injection and removal, ensuring operational efficiency and reliability.

The appd-instrumentation-manager.sh script empowers users with:

Automated Agent Management: Effortlessly injects and removes AppDynamics agents across diverse applications.
Flexible Controller Assignment: Enables different applications to report to distinct AppDynamics controllers, offering greater architectural freedom.
Enhanced Operational Reliability: Automates complex configuration tasks, reducing the potential for human error, misconfigurations, and application restarts.
Significant Efficiency Gains: Streamlines instrumentation workflows, leading to faster resolution times and reduced support overhead.

This utility is exceptionally effective for scenarios requiring precise manual instrumentation via initContainers and environment variables, especially across a large number of applications, providing a direct and reliable method for agent management.

✨ Key Features

Automated Agent Injection & Removal: Provides a single, unified command for seamless instrumentation and uninstrumentation.
Independent Operation: Functions without requiring a cluster agent, ensuring robust and flexible deployment options.
Flexible Controller Assignment: Supports reporting to distinct AppDynamics controllers for different applications, enhancing architectural adaptability.
Config-Driven Precision: Offers easy and precise targeting of Kubernetes Deployments and environment variables via intuitive YAML or CSV configuration files.
Hierarchical Configuration: Utilizes a powerful three-tier architecture (global > appTypeConfigs > deployments) for optimal control, reusability, and maintainability of settings.
Optimized Performance: Delivers lightweight and fast uninstrumentation processes.
Comprehensive Logging: Includes detailed logging capabilities for straightforward troubleshooting and operational insights.
Future-Ready Extensibility: Designed for easy expansion to support additional programming languages (e.g., PHP, Python).

🛠️ Usage Guidance

Prerequisites

Basic Linux command-line knowledge.
Access to your Kubernetes cluster where the applications are deployed.
kubectl installed and configured to interact with your cluster.

Ideal Use Cases

When a direct and reliable method is needed for instrumenting or uninstrumenting resources, especially in scenarios where cluster agent-based approaches may not be suitable or encounter issues.
When customers manually instrument applications via initContainers and use agent environment variables for configuration, particularly for a large number of applications.

⚙️ Configuration Setup Guidance

The AppD Instrumentation Manager uses configuration files to define how agents should be injected or removed.

1. Instrumentation Configuration (`config.yaml`)

The config.yaml file uses a three-tier hierarchical structure to manage AppDynamics agent settings, ensuring reusability, maintainability, and precise control.

Precedence Rules: More specific configurations override more general ones.
Deployment-specific settings > Application Type (Language) specific settings > Global settings

a. `global` Section

This section defines common AppDynamics settings that apply to all instrumented applications by default, regardless of their language or specific deployment. These serve as a baseline.

Example:

global:
  env:
    - name: APPDYNAMICS_CONTROLLER_HOST_NAME
      value: www.example.com
    - name: APPDYNAMICS_CONTROLLER_PORT
      value: "443"
    - name: APPDYNAMICS_CONTROLLER_SSL_ENABLED
      value: "true"
    - name: APPDYNAMICS_AGENT_ACCOUNT_NAME
      value: customer1
    - name: APPDYNAMICS_AGENT_ACCOUNT_ACCESS_KEY
      value: *********
    - name: APPDYNAMICS_AGENT_APPLICATION_NAME
      value: Demo_App

These values will be inherited by every deployment unless explicitly overridden.

b. `appTypeConfigs` Section

This section groups configurations based on the application's programming language (e.g., java, dotnet, nodejs). These settings are specific to how the AppDynamics agent integrates with that particular runtime environment and apply to all deployments of that specific appType.

For each appType, it defines:

env: Environment variables crucial for the agent's operation in that language (e.g., JAVA_TOOL_OPTIONS, CORECLR_PROFILER, NODE_OPTIONS).
volumes: Kubernetes volumes required by the agent (e.g., emptyDir for agent files).
volumeMounts: How these volumes are mounted into the application container.
initContainers: A critical component that copies the AppDynamics agent files into the shared volume before the main application container starts, ensuring agent availability. Each initContainer is tailored to the specific agent and its image.

Example for Java:

appTypeConfigs:
  java:
    env:
      - name: JAVA_TOOL_OPTIONS
        value: '-Dappdynamics.agent.reuse.nodeName=true -Dappdynamics.socket.collection.bci.enable=true -javaagent:/opt/appdynamics-java/javaagent.jar'
    volumes:
      - name: appd-agent-repo-java
        emptyDir: {}
    volumeMounts:
      - name: appd-agent-repo-java
        mountPath: /opt/appdynamics-java
    initContainers:
      - name: appd-agent-attach-java
        image: docker.io/appdynamics/java-agent:latest
        command: ["cp", "-r", "/opt/appdynamics/.", "/opt/appdynamics-java"]
        resources:
          limits:
            cpu: 200m
            memory: 75M
          requests:
            cpu: 100m
            memory: 50M
        securityContext:
          allowPrivilegeEscalation: false
          privileged: false
          readOnlyRootFilesystem: false
          runAsNonRoot: false
        volumeMounts:
          - mountPath: /opt/appdynamics-java
            name: appd-agent-repo-java

(Similar configurations for dotnet and nodejs are detailed in the project's config template.)

c. `deployments` Section

This is the most specific level. It lists individual Kubernetes deployments that need to be instrumented. Each entry here can override settings defined in the global or appTypeConfigs sections, allowing for fine-grained control for each application instance.

For each deployment, it typically includes:

name: The name of the Kubernetes Deployment resource.
namespace: The Kubernetes namespace where the deployment resides.
appType: Links the deployment to a specific configuration within the appTypeConfigs section (e.g., java, dotnet, nodejs). This determines which language-specific env, volumes, volumeMounts, and initContainers are applied by default.
env: A list of environment variables specific to this individual deployment. These variables will take precedence over any global or appTypeConfigs env variables with the same name.

Example Deployments:

deployments:
  - name: java-app
    namespace: java-apps
    appType: java
    env:
      - name: APPDYNAMICS_AGENT_TIER_NAME
        value: tomcat-tier
      - name: APPDYNAMICS_JAVA_AGENT_REUSE_NODE_NAME_PREFIX
        value: tomcat
  - name: tomcat
    namespace: ns2
    appType: java
    env:
      - name: APPDYNAMICS_AGENT_APPLICATION_NAME
        value: Demo_Tomcat_App # Overrides global
      - name: APPDYNAMICS_AGENT_TIER_NAME
        value: Demo-App-2-tier
      - name: APPDYNAMICS_JAVA_AGENT_REUSE_NODE_NAME_PREFIX
        value: Demo-App-2
      - name: APPDYNAMICS_CONTROLLER_HOST_NAME
        value: www.example-2.com # Overrides global
      - name: APPDYNAMICS_AGENT_ACCOUNT_ACCESS_KEY
        value: **************** # Overrides global
  # ... (other deployments like dotnet-app, nodejs-app)

This demonstrates how a single deployment can be configured to report to a different controller or use a different account access key than the global default, while still leveraging the common agent injection mechanism defined for Java applications.

2. Uninstrumentation Configuration (`uninstrument-config.csv`)

For uninstrumentation, the script uses a simple CSV file format. Each line specifies a resource to be uninstrumented.

CSV Format:
namespace,resource-type,resource-name,env-var

namespace: The Kubernetes namespace of the resource.
resource-type: The type of Kubernetes resource (e.g., deployment, statefulset).
resource-name: The name of the specific resource.
env-var: The environment variable used for agent injection (e.g., JAVA_TOOL_OPTIONS, JAVA_OPTS, CORECLR_PROFILER, NODE_OPTIONS).

Example Entries:

ns1,deployment,tomcat,JAVA_TOOL_OPTIONS
sts-ns1,statefulset,tomcat-statefulset,JAVA_OPTS

Getting Started

Follow these steps to get your AppD-Instrumentation-Manager up and running.

Building the Go Executable

The instrumentation logic is written in Go and needs to be compiled into an executable.

Download the Utility:
Download the AppD Instrumentation Manager zip file (e.g., AppD Instrumentation Manager_7cb66c7584594f9e8efd427605e1a5fb-041125-1709-4.zip) and unzip it.
```
# Example for a GitHub repository
git clone https://github.com/AppDynamics/appd-instrumentation-manager.git
```

Ensure output directories exist

mkdir -p <PROJECT_HOME_DIR>/bin/mac_os_amd64
mkdir -p <PROJECT_HOME_DIR>/bin/mac_os_arm64
mkdir -p <PROJECT_HOME_DIR>/bin/linux_amd64
mkdir -p <PROJECT_HOME_DIR>/bin/linux_arm64
mkdir -p <PROJECT_HOME_DIR>/bin/windows_amd64

Navigate to the Go module directory:

cd <PROJECT_HOME_DIR>/cmd-instrumentation/appd-instrumentation-manager-go

Build the executable. This command will place the compiled binary in the bin/ directory at the project root.

Build for Linux AMD64

GOOS=linux GOARCH=amd64 go build -o ../../bin/linux_amd64/instrumentation *.go

Build for Linux ARM64

GOOS=linux GOARCH=arm64 go build -o ../../bin/linux_arm64/instrumentation *.go

Build for Intel Macs

GOOS=darwin GOARCH=amd64 go build -o ../../bin/linux_amd64/instrumentation *.go

Build for Apple Silicon Macs

GOOS=darwin GOARCH=arm64 go build -o ../../bin/darwin_arm64/instrumentation *.go

Build for Windows AMD64

GOOS=windows GOARCH=amd64 go build -o ../../bin/linux_amd64/instrumentation.exe *.go

Instrumentation

To perform instrumentation, you'll use the config.yml file.

Prepare config.yml:
Copy the template configuration file to config.yml in your working directory (e.g., project root).
```
cp configs/config.yml.template config.yml
```
Edit config.yml:
Open config.yml and modify the parameters according to your specific instrumentation requirements (e.g., application names, agent paths, controller details). Refer to the comments within config.yml.template for guidance.
Run Instrumentation:
Execute the wrapper script, specifying the instrument action and your config.yml file.
```
./scripts/appd-instrumentation-manager.sh --instrumentation-enabled=true --config-file=config.yaml
```
Ensure the appd-instrumentation-manager.sh script has execute permissions:
```
chmod +x scripts/appd-instrumentation-manager.sh
```

Uninstrumentation

To perform uninstrumentation, you'll use the config.csv file.

Prepare config.csv:
Copy the template configuration file to config.csv in your working directory.
```
cp configs/config.csv.template config.csv
```
Edit config.csv:
Open config.csv and populate it with the details of the applications or agents you wish to uninstrument. The template provides the expected CSV format.
Run Uninstrumentation:
Execute the wrapper script, specifying the uninstrument action and your config.csv file.
```
/scripts/appd-instrumentation-manager.sh --instrumentation-enabled=false --config-file=config.csv
```
Ensure the batch-uninstrumentation.sh script (called by the wrapper) also has execute permissions:
```
chmod +x scripts/batch-uninstrumentation.sh
```

Contributing

Contributions are welcome! If you have suggestions for improvements, bug fixes, or new features, please feel free to:

Fork the repository.
Make changes to any required files and send them for review at vijayv05@cisco.com

This project is open-source and distributed under the terms of the Apache License.

❗ Important Disclaimer

This is an author-backed tool and is provided as an open-source utility.
If you have any queries or encounter issues while using this extension, please reach out to AppDynamics support. The owners are primarily available during the APAC time zone, and therefore, please expect potential delays if your ticket is logged during other geo time zones. Assistance will be provided based on the owners' availability and discretion.