How to use Service Accounts via the IaaS-API

About Service Accounts

Service Accounts allow you to access the whole STACKIT API programmatically. The IaaS-API allows attaching service accounts to servers which makes them available inside the VM. Accessing serviceaccounts inside a VM is possible through the metadata API on the well-known url http://169.254.169.254/stackit/v1/service-accounts. A service account is referenced by its service account mail which is globally unique.

The URL http://169.254.169.254/stackit/v1/service-accounts is part of the Server Metadata API and is only reachable from within a Server.

Creating Service Accounts

Service accounts can be created in the portal, the service account API or the STACKIT CLI.

Creating a Service Account with the STACKIT CLI

stackit service-account create --name <NAME>

Be sure to give the service account the correct permissions or roles for the intended tasks.

Connecting Service Accounts to Servers

The IaaS-API allows to attach or detach Service Accounts on already running servers or adding service accounts on creation of a server.

List Service Accounts of a Server

stackit curl https://iaas.api.eu01.stackit.cloud/v1/projects/{projectId}/servers/{serverId}/service-accounts

Attach a Service Account to a Server

stackit curl -X PUT https://iaas.api.eu01.stackit.cloud/v1/projects/{projectId}/servers/{serverId}/service-accounts/{serviceAccountMail}

Detach a Service Account from a Server

stackit curl -X DELETE https://iaas.api.eu01.stackit.cloud/v1/projects/{projectId}/servers/{serverId}/service-accounts/{serviceAccountMail}

Creating a Server with a Service Account

stackit server create --service-account-emails my-svc-acc@sa.stackit.cloud --name server1 --machine-type g1.1 [...]

Using Service Accounts inside a Server

After attaching the service account to a server it can immediately be used. The token of the service account is available through the server-local metadata API at http://169.254.169.254/stackit/v1/service-accounts.

Creating a short-lived token

Listing attached Service Accounts

curl http://169.254.169.254/stackit/v1/service-accounts

A token can be created and retrieved by calling the /token path.

Creating a Service Account Token

curl http://169.254.169.254/stackit/v1/service-accounts/<SERVICEACCOUNTMAIL>/token

Tokens have short lifetime and must be renewed regularly by retrieving a new token from this URL.

Usage with STACKIT CLI

To follow this example install the STACKIT CLI.

1. First we need to authenticate with the token
   Authenticate with the Token

stackit auth activate-service-account --service-account-token <TOKEN>

2. Then we can use the client as usual as the service account permissions allow.