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