Skip to main content

Akuity Agent

The Akuity Agent is a component installed into a managed cluster allowing it to be managed by an Argo CD instance on the Akuity Platform. Every cluster agent which is installed into Kubernetes clusters will have a corresponding cluster entry in Argo CD and will be available as an Argo CD Application destination.

Requirements​

To manage a cluster in the Akuity Platform, the cluster agent only needs outbound internet access to the Akuity Platform control plane. It is unnecessary for the Kubernetes API server endpoint to be public.

Installation​

To install and connect an agent, you must have already created an Argo CD instance in the Akuity Platform, as well as a kubectl context to a cluster you wish to be managed.

  1. Navigate to a single Argo CD instance.
  2. From the Clusters tab, click + Connect a cluster.
  3. Provide a name for the cluster and click + Connect cluster.
  4. Once the cluster entry has been created, installation manifests will be generated specific to the cluster.
  5. Copy the installation command and run in a terminal with kubectl context to your cluster.

The installation will install the required components into an akuity Namespace. Once the Akuity Agent shows as available in the Akuity Platform Portal, it is possible to deploy to the cluster using Argo CD.

Connecting to an Upbound MCP​

To connect an Argo CD instance on the Akuity Platform to an Upbound managed control plane (MCP), you must have already created an Argo CD instance and configured an Upbound MCP.

  1. Create a kubeconfig file for your Upbound MCP using the up ctx command . This example saves the kubeconfig to a file named mcp-kubeconfig.yaml.

    up ctx -a <organization> -f mcp-kubeconfig.yaml

    The resulting kubeconfig file will look like:

    apiVersion: v1
    clusters:
    - cluster:
        server: https://proxy.upbound.io/v1/controlPlanes/....
      name: upbound-akuity-dev
    contexts:
    - context:
        cluster: upbound-akuity-dev
        user: upbound-akuity-dev
      name: upbound-akuity-dev
    current-context: upbound-akuity-dev
    kind: Config
    preferences: {}
    users:
    - name: upbound-akuity-dev
      user:
        exec:
          apiVersion: client.authentication.k8s.io/v1
          args:
          - organization
          - token
          command: up
          env:
          - name: ORGANIZATION
            value: <your-organization>
          - name: UP_PROFILE
            value: <your-profile>
          interactiveMode: IfAvailable
          provideClusterInfo: false

    Store the server and ORGANIZATION field values from the kubeconfig as those will be necessary to connect to AKP ArgoCD.

  2. Go to Upbound console. Go to the My Account page and create a new Token from the API Tokens section.

Upbound Token

  1. Navigate to the required Argo CD instance in Akuity Platform.

  2. From the Clusters tab, click + Integration.

  3. Provide the name for the cluster.

  4. Choose Upbound option under Provider section inside the modal and put the Server, Token and Organization Name values you recorded previously in the respective input fields.

AKP Integration

  1. Click + Connect cluster.

  2. Once the cluster is connected, you will see a new entry in the cluster table with an upbound logo beside the name.

AKP Cluster

Upgrading​

Once installed, agents are automatically upgraded upon updates to Argo CD instances (e.g. upgrading Argo CD itself, resizing, applying new labels or annotations). When Argo CD configuration is updated, the agent version will be also be updated to the latest appropriate version compatible with the Argo CD instance.

Uninstalling​

To uninstall the Akuity Agent from a managed cluster:

  1. In Argo CD, first delete any applications which are currently deploying to the cluster. As a convenience, the Akuity Platform automatically labels all Argo CD Applications with cluster=<clustername> label, allowing you to easily filter applications by destination cluster name.
tip

If you wish to preserve existing resources in the cluster, or the cluster is no longer available, you can perform a non-cascaded delete. A non-cascaded delete is a non-destructive operation which deletes only the Argo CD application object, and none of the underlying resources in the cluster.

  1. Once all applications targeting the cluster have been removed, run the following commands to delete the agent resources:
kubectl delete namespace akuity
kubectl delete clusterrole akuity-agent-<cluster-name>
kubectl delete clusterrole akuity-argocd-application-controller-<cluster-name>
kubectl delete clusterrolebinding akuity-agent-<cluster-name>
kubectl delete clusterrolebinding akuity-argocd-application-controller-<cluster-name>

Alternatively, if you have downloaded the agent installation manifest you could execute:

kubectl delete -f akuity-manifests-<cluster-name>.yaml
  1. In the Portal UI, navigate to the Clusters tab of the Argo CD instance and click the trash icon next to the cluster to remove the entry.

FAQ​

Q: Why do the cluster URLs use HTTP? Clusters in open-source Argo CD use HTTPS.

A: In the Akuity Platform, every cluster URL is an alias for localhost, and there is no unencrypted communication that leaves the local application-controller pod on your cluster. You confirm this by checking an application-controller pod on your cluster. An easy way to check for this is to grep for the presence of hostAliases, like this:

kubectl get pod argocd-application-controller-<hash> -o yaml | grep -A 3 hostAliases

The output will be

  hostAliases:
  - hostnames:
    - cluster-<name>  # Where <name> is the name of your cluster.
    ip: 127.0.0.1