How to create a Komodor API key for automation

Komodor API keys inherit the permissions of the user they belong to. To give Terraform, a CI/CD pipeline, or another integration its own permissions, create a dedicated user for automation and generate an API key for that user.

This article calls that identity a programmatic user (you may also see it described as a service account or machine user). Assign it only the permissions your integration needs, and reserve it for automation.

Kubernetes ServiceAccounts shown in Kubernetes Explorer are separate identities and cannot be used for Komodor API access.

Before you begin

You need the following:

Permission to create users and assign Roles. This requires the manage:users action. Account admins have it by default.
Permission to impersonate users. Impersonation is controlled by an action in your Policy. As a best practice, restrict it to a small set of administrators.
An email address for the programmatic user. Use an address your organization controls and that is not used for interactive sign-in, such as a shared mailbox or an alias reserved for automation. If your organization enforces SSO, choose an address outside the SSO-managed domain so the user is not routed through SSO sign-in. Komodor uses the address for validation; the programmatic user does not need to sign in.
The list of operations your integration performs. You will map these to Komodor actions in the next step. See How To: Roles, Policies & Actions (User RBAC).

Step 1: Create a dedicated user

Go to Organization Settings (gear icon, top navigation bar). Under Access Management, select Users.
Click + Add User.
Enter a functional name that describes its purpose, such as terraform-automation, and the email address you prepared.
Select a Role and click Save.

The user receives an invitation email if the address can receive mail. The invitation does not need to be accepted for the steps below.

Step 2: Assign permissions

Apply least privilege. The programmatic user's Role and Policies define exactly what its API key can do, scoped to the clusters and namespaces you choose.

For example, a key used by the Komodor Terraform provider to manage Roles and Policies needs the manage:users action, and a key that registers clusters needs manage:integrations. A read-only reporting key can use the default-readonly-v2 policy or a narrower custom policy.

For details on creating Roles and Policies, see How To: Roles, Policies & Actions (User RBAC).

Step 3: Generate the API key

Because the programmatic user does not sign in, an administrator impersonates it to generate the key.

In the Users list, hover over the programmatic user's row and click the Impersonate (person) icon.
Accept the confirmation prompt. A banner at the top of the screen shows that you are in impersonation mode.
Open the profile menu in the top-right corner and select API Keys.
Click Generate Key, enter a description such as Terraform - production, and generate the key.
Copy the key and store it in a secrets manager. The key is displayed when it is generated.
Exit impersonation by clicking the X on the impersonation banner.

Komodor records that you started an impersonation session, and audits actions taken during the session as the impersonated user.

The key belongs to the programmatic user, not to the administrator who generated it. It continues to work if that administrator leaves the organization. Deleting the programmatic user, or changing its Role, changes what the key can do.

Step 4: Configure and verify your integration

Add the key to your integration. Komodor's public API accepts the key in the X-API-KEY header; see Using the Komodor API for details and the API reference.
Run a read operation your integration performs, such as listing clusters, and confirm it succeeds.
Run a representative write operation, such as a Terraform plan and apply on a test resource, and confirm it succeeds.
If a call returns 403 Forbidden, the programmatic user's Role or Policies do not include the required action or scope. Adjust them in Step 2 and retry.

Step 5: Rotate or revoke the key

To rotate a key:

Impersonate the programmatic user and generate a replacement key (Step 3).
Update the integration with the new key.
Confirm the integration works with the new key (Step 4).
Delete the old key from API Keys.

To revoke a key: users with the manage:users action can see and delete the organization's API keys from API Keys, without impersonating.

Expiration: if your organization has enabled API key expiration, keys generated for the programmatic user expire on the same schedule and stop working when they expire. Users with manage:users can edit or remove the expiration for a specific key. Schedule rotation before the expiry date so your automation is not interrupted.