API Name: Agent Install API
Manage and automate the deployment of the Lucidity agent across your entire cloud fleet.
API support for GCP instances is currently undergoing maintenance. We expect full functionality to be restored shortly
Overview
This API is used to programmatically trigger and monitor the installation of the Lucidity agent on your cloud instances. As a crucial prerequisite to onboarding the Lucidity agent, this process actively evaluates and provides essential instance details, including the supportability of the VMs, available disk slots, and partition details.
What does this API do?
Lucidity's Agent Install API enables you to programmatically trigger and manage the installation of the Lucidity agent across your cloud instances (AWS, Azure, and GCP). This allows you to seamlessly onboard virtual machines, whether you are deploying a single instance or scaling up an entire fleet, without requiring manual intervention.
Common Use Cases
Automated Deployment: Integrate agent installation directly into your CI/CD pipelines or infrastructure-as-code workflows.
Bulk Onboarding: Trigger agent installations on multiple instances simultaneously using batch requests.
Business Value
Automation: Eliminate manual SSH/RDP agent installations and streamline your infrastructure management.
Scalability: Easily onboard Hundred instances at once, accelerating your time-to-value.
Consistency: Standardise the installation process for both Linux and Windows environments through a single endpoint.
Multi-Cloud: Maintain a consistent operational workflow across AWS, Azure, and GCP.
Multi-Cloud Support The Lucidity API provides a unified interface across AWS, Azure, and GCP, automatically handling provider-specific parameter requirements during agent installation:
AWS: Requires the AWS Account ID.
Azure: Requires the Subscription ID and the specific Resource Group.
GCP: Requires the GCP Project ID.
Lifecycle
SCHEDULED Job created successfully (Returns unique Job id)..
IN_PROGRESS Agent installation is currently executing on the instance.
INSTALLED Agent successfully installed.
FAILED Installation encountered an error (Check failureMessage).
1. Trigger Agent Installation Purpose: Initiate the installation of the Lucidity agent on one or multiple cloud instances.
ENDPOINT: POST /external/client/api/v1/agent/install
Best Practices
Security
Never log or commit API tokens to version control.
Use secure credential storage (vaults, secret managers)
Rotate access tokens regularly, as they are short-lived.
Use HTTPS only for all API communications.
Performance & Reliability
Batch your requests: Send 100 installation requests in a single API call array to reduce network overhead.
Cost Optimization
Ensure instances are ready: Only trigger installations on fully provisioned, running instances to avoid wasted API calls and failed jobs.
Operational Excellence
Track Job IDs: Always log the id (Job ID) returned in the 202 OK response to monitor the asynchronous installation progress.
Monitor Failure Messages: Implement logging and alerting for any non-null failureMessage fields returned in the response array.
Use Retry logic strategically: Set retryAgentInstallation to true only when you are explicitly trying to overcome a known, transient prior failure.
FAQ
General Questions
Q: Can I install the agent on multiple instances at once? A: Yes, the API accepts an array of objects in the requests payload, allowing you to trigger installations on multiple instances across different clouds in a single call.
Q: What operating systems are supported by this API? A: The API supports both LINUX and WINDOWS operating system types.
Q: How do I know if the installation failed? A: If the failure is immediate, the response will include a failureMessage If the failure happens asynchronously, you can track the status using the returned Job id.
Technical Questions
Q: Is the resourceGroup parameter always required? A: No, resourceGroup is only required when targeting Azure instances. For AWS and GCP instances, this field should be omitted.