Guides / Access and automation

Automate with a service account

When a pipeline or a script needs to call the API, it should not use a person's token, which carries all of that person's rights. Give it a service account with only the rights it needs.

1. Create the service account, a role and a binding

The role below lets the account manage VPCs, accounts, DNS and DHCP, and nothing else. The binding gives the role to the service account.

kubectl --server https://acme-prod-api.etorm.com --token "$ETORM_TOKEN" apply -f - <<'YAML'
apiVersion: iam.etorm.com/v1alpha1
kind: ServiceAccount
metadata: {name: ci}
spec: {}
---
apiVersion: iam.etorm.com/v1alpha1
kind: Role
metadata: {name: network-deployer}
spec:
  rules:
    - {apiGroups: [network.etorm.com], resources: [vpcs, accounts, dnsservices, dhcpservices], verbs: [get, list, watch, create, update, patch, delete]}
---
apiVersion: iam.etorm.com/v1alpha1
kind: RoleBinding
metadata: {name: ci-network-deployer}
spec:
  roleRef: {name: network-deployer}
  subjects: [{kind: ServiceAccount, name: ci}]
YAML

A role can never grant more than its author holds, and a binding needs the right to grant that role. If you only need a built-in role, bind editor or network-admin instead of writing one.

2. Create a token for it

Name the token after the month you issue it, so you can tell old from new when you rotate.

kubectl ... apply -f - <<'YAML'
apiVersion: iam.etorm.com/v1alpha1
kind: APIToken
metadata: {name: ci-2026-12}
spec:
  subject: {kind: ServiceAccount, name: ci}
  description: CI deploys
  expiresAt: "2027-03-01T00:00:00Z"
YAML

The response contains the full token once, in status.token. We keep only a hash, so this is your one chance to read it. Ask for JSON output, put the token in your CI's secret store, and make sure nothing logs it. Tokens below platform level expire, after 90 days by default and 365 at most.

3. Rotate the token

Create the new token and switch the pipeline to it. Once the pipeline works with the new one, delete the old one.

kubectl ... delete apitoken ci-2026-09

Deleting the service account and recreating it with the same name does not bring old tokens back. A token is tied to the principal it was issued for, not to the name.

4. Check what it may do

Before you hand the token to a pipeline, ask the API whether the service account can do what the pipeline needs. This example asks whether it may create a VPC.

curl -sS -H "Authorization: Bearer $ETORM_TOKEN" -H "Content-Type: application/json" \
  -X POST https://api.etorm.com/clusters/acme-prod/apis/authorization.k8s.io/v1/subjectaccessreviews \
  -d '{"apiVersion":"authorization.k8s.io/v1","kind":"SubjectAccessReview","spec":{"user":"serviceaccount:acme-prod:ci","resourceAttributes":{"verb":"create","group":"network.etorm.com","resource":"vpcs"}}}'

The answer is in status.allowed. Owners and IAM admins can ask about another principal. Everyone else gets 403 for such a question.

Clean up

kubectl ... delete apitoken ci-2026-12
kubectl ... delete rolebinding ci-network-deployer
kubectl ... delete role network-deployer
kubectl ... delete serviceaccount ci

Next

Manage Etorm with OpenTofu.