ServiceAccounts

Kargo ServiceAccounts enable programmatic access to Kargo APIs without requiring a user to share short-lived credentials with non-human agents, such as a CI process.

note

Not what you were looking for?

If you're looking to use the built-in, system-level ServiceAccounts, refer to the Operator Guide's ServiceAccounts documentation.

Understanding Kargo ServiceAccounts

A Kargo ServiceAccount is a Kubernetes ServiceAccount resource that has been specially labeled with rbac.kargo.akuity.io/service-account: "true" to identify it as being intended for use with Kargo.

Project admins, or others with sufficient permissions, are able to create and delete ServiceAccounts, assign roles to them or revoke roles from them, and create and delete associated authentication tokens.

Managing ServiceAccounts

Project admins can manage ServiceAccounts within their project namespace using the kargo CLI or declaratively using Kubernetes manifests (i.e., GitOps'ing them).

Creating ServiceAccounts

Using the UI

info

UI support for this feature is not yet implemented.

Using the CLI

To create a ServiceAccount using the kargo CLI:

kargo create serviceaccount --project my-project my-sa

serviceaccount/my-sa-token created

Then list ServiceAccounts to verify:

kargo get serviceaccounts --project my-project

NAME    AGE
my-sa   30s

Declaratively

ServiceAccounts can be managed declaratively using Kubernetes manifests:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: my-sa
  namespace: my-project
  labels:
    rbac.kargo.akuity.io/service-account: "true"

info

The rbac.kargo.akuity.io/service-account: "true" label identifies the resource as a Kargo ServiceAccount. The ServiceAccount is still completely usable without this label (i.e. can still be used to interact with Kargo APIs programmatically), however, neither the UI nor kargo CLI will recognize it as being a Kargo ServiceAccount.

note

When managing resources declaratively (e.g., via GitOps), do not include a rbac.kargo.akuity.io/managed: "true" annotation. Resources with this annotation can be modified or deleted via the Kargo API, which may conflict with declarative management.

Assigning Roles

Using the UI

info

UI support for this feature is not yet implemented.

Using the CLI

Grant a Kargo Role to a Kargo ServiceAccount:

kargo grant --project my-project \
  --role developer \
  --service-account my-sa

role.rbac.kargo.akuity.io/developer updated

info

A Kargo Role is an abstraction over a trio of ServiceAccount, Role, and RoleBinding Kubernetes resources. When you grant a Kargo Role to a Kargo ServiceAccount, the Kargo Role's underlying Kubernetes RoleBinding resource is updated to include the Kargo ServiceAccount as a subject. For more details about Kargo roles, see the Access Controls documentation.

Declaratively

You can also manage role assignments declaratively:

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: developer
  namespace: my-project
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: developer
subjects:
- kind: ServiceAccount
  name: my-sa
  namespace: my-project

Creating Authentication Tokens

Using the UI

info

UI support for this feature is not yet implemented.

Using the CLI

To generate a new authentication token for a Kargo ServiceAccount:

kargo create serviceaccounttoken --project my-project \
  --service-account my-sa my-sa-token

Token created successfully!

IMPORTANT: Save this token securely. It will not be shown again.

Token: eyJhbGciOiJSUzI1NiIsImtpZCI6IjdwQ0...

danger

The token value is displayed only once during creation. Do not lose it!

If you lose the token value, you must delete the token and create a new one or the existing token's value can be retrieved by a user with sufficient permission using kubectl instead of the kargo CLI.

List all authentication tokens:

kargo get serviceaccounttokens --project my-project

NAME          SERVICE ACCOUNT   KARGO MANAGED   AGE
my-sa-token   my-sa             true            5m

List authentication tokens for a specific ServiceAccount:

kargo get serviceaccounttokens --project my-project \
  --service-account my-sa

Retrieve details about a specific token (note that the token value will be redacted):

kargo get serviceaccounttoken --project my-project \
  my-sa-token -o yaml

Declaratively

Authentication tokens can be created declaratively:

apiVersion: v1
kind: Secret
metadata:
  name: my-sa-token
  namespace: my-project
  labels:
    rbac.kargo.akuity.io/service-account-token: "true"
  annotations:
    kubernetes.io/service-account.name: my-sa
type: kubernetes.io/service-account-token

info

Kubernetes will automatically populate the token data asynchronously. The rbac.kargo.akuity.io/service-account-token: "true" label is required to identify the Secret as a Kargo ServiceAccount token.

For more information about ServiceAccount token secrets, see the Kubernetes documentation.

Using Authentication Tokens

Authentication tokens can be used with many Kargo or Kubernetes clients. This includes tools like kubectl as well as any programming language client library for Kubernetes or Kargo.

note

While the kargo CLI does not directly support specifying a token via command line flags, you can configure it to use a token by editing ~/.config/kargo/config.

Deleting Authentication Tokens

Using the UI

info

UI support for this feature is not yet implemented.

Using the CLI

To delete a token when it's no longer needed or to rotate credentials:

kargo delete serviceaccounttoken --project my-project \
  my-sa-token

serviceaccounttoken.kargo.akuity.io/my-sa-token deleted

Verify the token has been deleted:

kargo get serviceaccounttokens --project my-project

Declaratively

To delete a token declaratively, simply remove the Secret resource from your manifests.

Revoking Roles

Using the UI

info

UI support for this feature is not yet implemented.

Using the CLI

Revoke a Kargo Role from a ServiceAccount:

kargo revoke --project my-project \
  --role developer \
  --service-account my-sa

role.rbac.kargo.akuity.io/developer updated

This removes the ServiceAccount from the Kargo Role's underlying Kubernetes RoleBinding resource.

Declaratively

To revoke a role declaratively, remove the ServiceAccount from the subjects list in the RoleBinding resource.

Deleting ServiceAccounts

Using the UI

info

UI support for this feature is not yet implemented.

Using the CLI

To delete a ServiceAccount when it's no longer needed:

kargo delete serviceaccount --project my-project my-sa

serviceaccount/my-sa deleted

warning

Deleting a Kargo ServiceAccount via the kargo CLI automatically deletes all associated authentication tokens as well.

Verify the ServiceAccount has been deleted:

kargo get serviceaccounts --project my-project

Declaratively

To delete a ServiceAccount declaratively, simply remove the ServiceAccount resource from your manifests.

warning

Deleting a ServiceAccount will invalidate all associated authentication tokens. Be sure to also remove any associated Secret resources containing tokens.

CLI Aliases and Shortcuts

The kargo CLI supports convenient aliases for Kargo ServiceAccount commands:

• serviceaccount, serviceaccounts, sa, sas all refer to Kargo ServiceAccounts.
• serviceaccounttoken, serviceaccounttokens, sat, sats all refer to authentication tokens.

For example:

kargo get sas --project my-project

kargo create sat --project my-project \
  --service-account my-sa my-sa-token-1