About the Aembit Agent Controller

Aembit’s Agent Controller is a critical Aembit Edge component that serves as the registration broker for other Edge Components within your operational environments. It acts as the trusted intermediary that enables Agent Proxies to securely register with Aembit Cloud and obtain the credentials needed for Access Policy enforcement.

Agent Controller simplifies the deployment and management of Aembit Edge by centralizing the registration process and providing a secure communication channel between your distributed Edge components and Aembit Cloud.

Deployment options

Agent Controller supports deployment across diverse computing environments to meet your infrastructure requirements:

Virtual machines

Deploy Agent Controller on dedicated virtual machines using native installers:

Linux virtual machines Ubuntu and Red Hat Enterprise Linux

→

Windows virtual machines Windows Server

→

Container environments

Deploy Agent Controller within containerized environments:

Kubernetes clusters Deployed via Helm charts with automatic configuration

→

AWS ECS Fargate Container-based deployment using Terraform modules

→

Specialized deployments

Support for specialized deployment scenarios:

AWS Lambda deployments Supports Edge component deployment in AWS Lambda

→

High availability configurations Multiple instances with load balancing for production resilience

→

Deployments without Agent Controller

In some deployment models, like Aemibt CLI for CI/CD and when your applications use the Aembit API directly, you may not need an Agent Controller, reducing operational complexity.

For more details, see Aembit Edge on CI/CD services.

Key responsibilities

Agent Controller performs multiple critical functions within the Aembit Edge architecture:

• Controller Self-Registration - The Agent Controller manages its own registration and attestation with Aembit Cloud to establish a foundational trust relationship for the environment it represents.

• Token Provisioning - Once registered, Agent Controller provides authentication tokens to Agent Proxies. The controller handles local token distribution, while Aembit Cloud centralizes the actual token management.

• Trust establishment - Establishes and maintains trust relationships between your environment and Aembit Cloud. Validates identity evidence from Trust Providers to ensure only authorized components can participate in the Aembit ecosystem.

• Secure communication - Manages TLS communication between Agent Proxies and itself, providing encrypted channels for sensitive registration and authentication data.

How Agent Controller works

Agent Controller operates as part of the broader Aembit Edge registration and credential injection workflow:

During registration

Agent Controller supports the following registration methods, each with its own workflow:

Trust Provider-based

Agent Controller uses Trust Providers which automate identity attestation through cloud provider metadata services or other trusted systems in your environment. Ideal for production and high-availability deployments.

1. Agent Controller attestation - Agent Controller retrieves an attestation document from its local environment. Trust Providers exist in Aembit Cloud and can verify that Agent Controller has provided an attestation document that matches the Trust Provider configured for that Agent Controller.
2. Agent Controller registration - Using the attestation, Agent Controller obtains an access token from Aembit Cloud and completes its secure registration
3. Agent Proxy token flow - Agent Proxies request tokens from Agent Controller which obtains them from Aembit Cloud on their behalf
4. Agent Proxy registration - Using the token provided by Agent Controller, Agent Proxies register with Aembit Cloud and establish their secure connection
5. Health reporting - Agent Controller periodically sends health reports to Aembit Cloud

Device Code-based

Device Codes are temporary one-time-use codes, valid for 15 minutes, that you use during installation to authenticate the Agent Controller with your Aembit Tenant.

Device Codes vs Trust Providers

Device Codes provide an alternative authentication method for your Agent Controller with Aembit Cloud. However, Aembit recommends configuring Trust Providers instead, as they offer superior control and flexibility in attestation.

In some environments, attestation may require Agent Controllers to use Device Codes as a fallback mechanism.

See About the Aembit Agent Controller for more information.

1. Device code flow - Agent Controller requests a device code from Aembit Cloud and polls for an access token
2. Agent Controller registration - Using the access token, Agent Controller completes its secure registration with Aembit Cloud
3. Agent Proxy token flow - Agent Proxies request tokens from Agent Controller, which obtains them from Aembit Cloud on their behalf
4. Agent Proxy registration - Using the token provided by Agent Controller, Agent Proxies register with Aembit Cloud and establish their secure connection
5. Health reporting - Agent Controller periodically sends health reports to Aembit Cloud

During operation

Once registered, Agent Controller plays a continuous, active role in your Aembit Edge deployment. Its main operational responsibilities include:

1. Token Management and Refresh
   • Proxy Token Requests - Agent Proxies periodically request new access tokens from Agent Controller. This ensures that Agent Proxies always have valid credentials to interact with Aembit Cloud.
   • Token Refresh - Agent Controller securely stores refresh tokens and uses them to obtain new access tokens from Aembit Cloud as needed, without requiring re-registration.
2. Health Reporting
   • Periodic Health Checks - Agent Controller sends a health report to Aembit Cloud every minute over a secure connection. This report includes status, version, and uptime, enabling monitoring in your Aembit Tenant UI.
   • Status Updates - The Aembit Tenant UI displays the current health of each Agent Controller, including connection status and last reported uptime.
3. TLS Certificate Reporting
   • Certificate Status - If you enable TLS, Agent Controller reports its certificate status to Aembit Cloud. The Aembit Tenant UI displays certificate health, including expiration warnings.
4. Metrics and Observability
   • Metrics - Agent Controller provides Prometheus-compatible metrics, allowing integration with monitoring tools for timely observability of operational health, request rates, and resource usage.

Monitoring and health

Agent Controller provides robust monitoring and health reporting features to help you maintain operational visibility and ensure reliability in your Edge deployments.

Where to find Agent Controller logs

Agent Controller logs are essential for monitoring its operation and troubleshooting issues. The log file locations vary based on the operating system:

Linux

On VM deployments the logs should be available with the command:

journalctl -n aembit_agent_controller

This is the primary location for all Agent Controller service activity logs on Linux.

Windows

Agent Controller writes logs to:

C:\ProgramData\Aembit\AgentController\Logs

This is the primary location for all Agent Controller service activity logs on Windows. Logs aren’t removed on uninstall.

What ReportHealth logs look like

When Agent Controller sends a health report to Aembit Cloud, you’ll see log entries like:

On Success:

Cloud Health Reporting Service sent the Health Report to the Cloud successfully.

On Failure:

Error while getting Report Health from gRPC

Tip

If you’re troubleshooting health reporting, look for these log entries in the Agent Controller logs. A successful message means Agent Controller is reporting health status to Aembit Cloud; errors indicate connectivity or configuration issues.

Health reporting

Automatic Health Checks - Agent Controller sends a health report to Aembit Cloud every minute over a secure connection. This report includes the controller’s status, version, and uptime.

Status Indicators in your Aembit Tenant UI

• Healthy - Displayed as a green dot in the Aembit Tenant UI if Agent Controller sends a healthy status to Aembit Cloud within the last 90 seconds.
• Disconnected - If Agent Controller reports no healthy status within 90 seconds, a disconnected icon appears.
• Last Reported Uptime - Hovering over the status icon shows the last reported uptime for the Agent Controller.

Health States

• Healthy - Registered and connected to Aembit Cloud.
• Registered - Registered but not fully healthy (for example, waiting for additional attestation).
• Unregistered - Not registered with device code or trust provider.
• RegisteredAndNotConnected - Registered, but the connection to Aembit Cloud is down.

TLS status

The TLS column in the Agent Controller list provides an at-a-glance view of each controller’s TLS certificate status for Agent Controller communication with Agent Proxies. This helps identify expiring or misconfigured certificates.

Note

This TLS status refers to Agent Controller’s own certificates for secure communication with Agent Proxies and Aembit Cloud. This is separate from TLS Decrypt certificates, which Agent Proxy manages for decrypting application traffic. For TLS Decrypt certificate monitoring, see Configure TLS Decrypt.

The TLS status uses color-coded icons (and sometimes tooltips) to show the health of the Agent Controller’s TLS certificate:

• Green: More than 30 days until certificate expiration.
• Yellow: Certificate expires within 30 days.
• Red: Certificate expires within 7 days or is already expired.
• Blue: (For Aembit-managed TLS) Indicates the certificate is valid, managed by Aembit, and automatically rotates them.
• Grey/Not configured: TLS isn’t configured for this Agent Controller.

Metrics and observability

Agent Controller exposes operational metrics to help you monitor performance and health:

• Key metrics tracked include:
  • Request rates (for example, token issuance, registration)
  • Latency and error rates
  • Resource utilization (CPU, memory)
  • Active connections and uptime
• Prometheus-compatible metrics - Agent Controller provides operational metrics in Prometheus format. This enables integration with observability platforms for rapid monitoring and alerting.
  See Aembit Edge Prometheus-compatible metrics for details.

High availability considerations

For production deployments, configure Agent Controller in a high availability setup:

• Redundancy - Multiple Agent Controller instances remove single points of failure.
• Load Balancing - TCP load balancers distribute traffic across healthy instances.
• Health Monitoring - Automated health checks detect failures and trigger remediation.
• TLS Management - Proper certificate configuration for load-balanced environments.

Security features and best practices

Agent Controller incorporates multiple security mechanisms:

TLS encryption

Agent Controller supports both Aembit-managed and customer-managed PKI for securing communication between itself and Agent Proxies:

• Aembit PKI configuration - Default option for ease of use managed by Aembit
• Customer PKI configuration - For organizations with existing PKI infrastructure

Identity validation

Agent Controller may use Trust Providers to authenticate itself with Aembit Cloud, enabling it to provide tokens for the deployment.

Agent Controller supports a limited set of Trust Providers for authentication:

• AWS IAM Roles and EC2 Instance Identity
• Azure Managed Identity
• Google Cloud Service Accounts

See the Aembit Support Matrix Agent Controller Trust Providers section for details.

Note

This only applies when using Trust Provider-based authentication. As a best practice, use Trust Provider-based registration in production environments. Use Device Code-based registration only for testing or proof-of-concept deployments.
See During registration for more details.

Integration with the Aembit ecosystem

Agent Controller is a core part of the Aembit Edge architecture, acting as the bridge between distributed Edge components and the Aembit Cloud control plane. It enables secure registration, policy retrieval, and health monitoring across your environment.

Related topics

• About TLS Decrypt - Learn how Agent Proxy performs TLS decryption with Agent Controller support
• Agent Proxy installation - Install the component that performs TLS decryption
• Trust Providers - Identity attestation for secure registration
• Aembit Edge - Overview of Aembit’s Edge architecture
• Aembit Cloud - Overview of Aembit’s Cloud control plane