Skip to main content

Connect a Kargo Agent

After your new Kargo instance is created successfully (Healthy status next to your new instance's name):

  1. Navigate to Kargo → your instance → Agents.

  2. Click + Register an agent to add a Kargo Agent.

  3. Input your Agent Name.

  4. Choose agent hosting option: Kargo agents may be hosted and run on the Akuity Platform control-plane, or they can be self-hosted and installed into an on-premises cluster behind corporate firewalls.

    Select the self-hosted agent option if Kargo needs to run Kubernetes Jobs as part of testing/verification, or if Kargo needs to interface with private, self-hosted services including:

    • private Git servers
    • internally accessible metric providers (e.g. self-hosted Prometheus)
    • self-managed Argo CD

    Otherwise, if using public git providers (GitHub, GitLab), public metric providers (DataDog, CloudWatch, NewRelic), and Akuity Platform-managed Argo CD, the agent can be hosted/managed by the Akuity Platform.

    caution

    AnalysisTemplates/AnalysisRuns that use Kubernetes Jobs will never complete if the agent is Akuity Platform-managed. You must use a self-hosted agent if your verifications require Kubernetes Jobs.

  5. (Optionally) Kargo can interface with Argo CD instances to sync applications, reflect application health, and verify successful sync operations during promotion. To connect your agent to an Argo CD instance managed by Akuity Platform, select the name of the instance in the Akuity Managed Argo CD option. If this agent is connecting to a self-hosted Argo CD, leave this unselected and install the agent into the cluster where Argo CD is running.

  6. (Optionally) You can choose to set your agent to be the default agent by setting Set as Default Shard. It is by default set to true for the first agent you connect but you can override it by setting a different agent as default later.

  7. Click Connect.

  8. If you opted for Self-hosted Kargo Agent then you would need to click on the Install option shown beside the newly created agent in the table. This will display the Install Akuity Agent popup. Click Copy to Clipboard

    caution

    Before pasting the next command, make sure you're connected to the correct cluster.

Paste the copied command into your terminal and run it to apply the agent manifest.

Alternatively, you can download the agent manifest and apply it manually inside your cluster.

caution

When uninstalling the self-hosted agent, remove it from the AKP Kargo agent list, then run the provided cleanup command in your cluster to ensure all resources are properly removed. Avoid deleting the namespace directly, as this may cause resources to remain stuck in the terminating phase.

After installing the agent into your Kargo Agent, you should see the agent listed in the Akuity dashboard with a green heart icon next to the agent name.

If you chose to let Akuity manage the agent then you can skip the above steps.

Now that your Kargo instance is connected to a Kargo Agent, move on to the next section to learn about enabling remote access to your instance.