UA Deployment

You can deploy a Universal Agent through the portal or programmatically through the API. Choose portal deployment for a guided setup of smaller deployments, or API deployment when automating programmatic or partner-driven fleet rollouts at scale.

All Universal Agent deployments require a provisioning token.

About Provisioning Tokens

A provisioning token securely registers Universal Agents over the Kentik API without requiring manual portal access or long-lived credentials. Upon initial startup, the agent reads the token from the K_REGISTER_PROVISIONING_TOKEN environment variable to register itself directly. You can configure tokens to auto-approve agents immediately or hold them in a Not Authorized status until an administrator grants approval. This mechanism provides a low-risk, fully scriptable onboarding workflow across standalone Linux hosts, Docker containers, and Kubernetes clusters.

Provisioning tokens enforce the following security and multi-tenant rules:

• Organization Scope: Kentik strictly binds each token to a single organization, preventing you from transferring an agent to another organization post-registration.

• Short Lifespan & Usage Caps: Custom expiration schedules and strict usage caps (maxUsageCount) eliminate long-lived credential risks.

• Runtime Token Updates: The K_REGISTER_PROVISIONING_TOKEN environment variable overrides install-time credentials, allowing you to replace expired tokens without reinstalling the agent binary.

• Partner & Third-Party Onboarding: Partner teams and system integrators can deploy agents into a customer organization safely over the API without requiring portal login access or persistent credentials.

• Clean Staging & Org Locking: Because registered agent identities are permanently tied to the issuing organization, staging agents in a lab organization requires re-registering them with a customer-scoped token before customer deployment.

Token Authorization Statuses

The following table describes token authorization statuses for portal and API deployments.

Token Revocation & Risk Management

To maintain a minimal exposure window, set a strict maxUsageCount and short expiry when creating a provisioning token. Once all intended agents in a deployment run have registered, you can immediately revoke the token via the kagent provisioning-tokens API. Revoking a provisioning token prevents new agents from registering with those credentials while leaving already registered and authorized agents unaffected.

Deploy a Universal Agent Through the Portal

To deploy a new instance of the Universal Agent via Docker or Linux through the portal, follow these steps:

1. Navigate to the Universal Agents page via Settings » Universal Agents in the Kentik portal’s main nav menu.

2. Click + Deploy Agent to open the dialog.

3. Under Installation, select Docker or Linux and click the corresponding tab.
   The generated command that appears automatically bundles your company ID (K_COMPANY_ID) and a provisioning token (K_REGISTER_PROVISIONING_TOKEN).

4. Click Copy to copy the command from the text area.

5. Open a terminal window on the host machine and paste the command. (To use a web proxy, see Install Agent via Web Proxy).

6. Run the command. The new agent will appear in the Select an Agent list. The Host Name column will vary as follows:

   1. Docker: The agent's Docker container ID.

   2. Linux: The hostname of the Linux system where the agent was installed.

7. Click Authorize to authorize the agent to connect with Kentik. The dialog will refresh with basic information, optional fields, and a Continue button.

   

8. Optionally add Display Name, Description, and Site Name. Click Continue to proceed.

9. Select the capabilities to enable for this agent by clicking the toggle switch next to each capability.

   

10. Click the Finish button to complete the deployment process. Once deployed, the agent will appear on the Universal Agents List.

Tip: If you close the dialog before clicking Authorize, the agent will appear on the Universal Agents List with a “Not Authorized“ status and won't be functional. To resolve this, click Deploy Agent to reopen the dialog and click Authorize.

Note: A token generated through a portal installation has a time-to-live (TTL) of one hour. You can register as many agents as you wish during that one-hour window before requesting a new token. After this timeframe, you will need to re-run the generated command in Step 3 to generate a new provisioning token and continue installations.

Install Agent via Web Proxy

Use the https_proxy environment variable to set the proxy's URL:

• Docker: Provide the environment variable as part of the docker run command:

  --env https_proxy=http://address.of.your.proxy

• Linux: Set the environment variable before running the install command:

  export https_proxy=http://address.of.your.proxy

Deploy a Universal Agent Through the Kentik API

For portal-free automated universal agent deployments across hosts, Docker, or Kubernetes clusters, follow these steps:

Notes:

• Before starting, ensure you have the following:

  • A Kentik API user (email + API token) for the target organization.  

  • The target organization's company ID.  

  • Network Egress to grpc.api.kentik.com (US) or grpc.api.kentik.eu (EU) on port 443.

1. Create a provisioning token in the target organization by executing a POST request against the API host for the target organization's region.
   The account you authenticate with determines which organization the token belongs to.

   curl -sS -X POST \
     -H "Content-Type: application/json" \
     -H "X-CH-Auth-Email: $K_API_EMAIL" \
     -H "X-CH-Auth-API-Token: $K_API_TOKEN" \
     -d '{
       "name": "poc-fleet",
       "maxUsageCount": 5,
       "requiresApproval": false,
       "config": { "siteId": "1234" }
     }' \
     https://grpc.api.kentik.com/kagent/v202401/provisioning-tokens

   Tip: You can customize the token's expiration schedule when creating it via the Provisioning Tokens API by passing a future ISO 8601 timestamp in the expiresAt payload attribute, for example:

   "expiresAt": "2026-07-04T12:18:53.092Z"

   See the Provisioning Tokens API reference for full schema details.

2. Extract the token value by locating the generated token string within the JSON response under .token.token.
   This value is the secure credential that must be handed to the deploying agents.

3. Deploy the agents with the token.

   1. Standalone Linux or Docker: Supply the token directly to the host's bootstrap environment before launching the agent service:

      export K_COMPANY_ID=<target-company-id>
      export K_REGISTER_PROVISIONING_TOKEN=<token-value>

      Note: The K_REGISTER_PROVISIONING_TOKEN variable overrides any values stored at install time, allowing you to update expired tokens without reinstalling the agent.

   2. Kubernetes (Helm):
      Pass the company ID and token as strings into the chart parameters during installation:

      helm install kagent https://github.com/kentik/kagent-helm/archive/refs/heads/main.tar.gz \
        --set-string kagent.companyId=<target-company-id> \
        --set-string kagent.provisioningToken=<token-value>

      Notes:

      • Set maxUsageCount on the token to at least the number of replicas you deploy, as each individual pod will consume one use.

      • If you are using the Kubernetes Helper, you can also use the generate-provisioning-token.sh helper script included in the kagent-helm repository to automate token creation.

      • Deploy Universal Agents with Helm provides more information for deploying Universal Agents with Helm.

4. Retrieve the agent's install ID by querying the API to list all agents awaiting authorization within the target organization to capture your specific install.id:

   # List agents awaiting authorization to get the install ID
   curl -sS -H "X-CH-Auth-Email: $K_API_EMAIL" -H "X-CH-Auth-API-Token: $K_API_TOKEN" \
     "https://grpc.api.kentik.com/kagent/v202401/agents?unregistered=true" \
     | jq -r '.agents[] | "\(.install.id)\t\(.install.hostMetadata.hostname)"'

5. Authorize the agent by submitting a PUT request containing the retrieved install-id to complete the secure verification process.
   The API response returns a permanent, numeric agent-id.

   curl -sS -H "X-CH-Auth-Email: $K_API_EMAIL" -H "X-CH-Auth-API-Token: $K_API_TOKEN" -X PUT \
     "https://grpc.api.kentik.com/kagent/v202401/agents/authorize/<install-id>"

6. Enable and configure agent capabilities programmatically.
   Once the agent status shows as Up, enable specific capability names via PATCH request using the returned agent-idname:

   curl -sS -H "X-CH-Auth-Email: $K_API_EMAIL" -H "X-CH-Auth-API-Token: $K_API_TOKEN" \
     -X PATCH -H "Content-Type: application/json" \
     -d '{"enabled":true}' \
     "https://grpc.api.kentik.com/kagent/v202401/agents/<agent-id>/capabilities/kproxy"

   Tip: If you deploy an agent using an auto-approve token (requiresApproval: false), the agent is automatically authorized upon initial registration. You can skip the step to Authorize the agent and proceed directly to managing capabilities.