Create a service account

A service account is a non-human identity that automated work, such as CI pipelines and applications, use to authenticate to evroc. This guide shows how to create a service account and generate a credential for it, using either the evroc CLI or the evroc Console.

For an overview of what a service account is and why you'd use one, see service accounts.

Before you begin

  • You're an administrator of the project, or you have at least the iam.serviceAccounts.create permission.
  • CLI - You've installed and authenticated the evroc CLI, with your current context set to the project you want to create the service account in.
  • Console - You can sign in to the evroc Console.

Choose a service account name

Give the service account a name that describes the workload it serves, for example ci-deploy or storage-ingest. The name is unique within the project and is used in the service account's fully qualified identifier.

Create the service account

Via the CLI

Create the service account with evroc iam serviceaccount create. The service account is created enabled by default; use --enabled=false to create it disabled.

evroc iam serviceaccount create ci-deploy --description "CI deployment pipeline"

A disabled service account can't authenticate, even if it has a credential and role bindings. You can enable it later with ev roc iam serviceaccount update ci-deploy --enabled.

Via the console

  1. Sign in to the evroc Console.
  2. Open a project from the Explorer.
  3. Navigate to IAM > Users for the project.
  4. Select Service Accounts.
  5. Click Create a Service Account.

Configue the following:

  • Service Account ID - The name that identifies the service account within the project, and the value you use to grant roles to it.
  • Description - An optional note about what the service account does.
  • Roles - The role the service account recieces froma list of predefined set of permissions.

Generate a credential

A service account can't authenticate until it has a credential. When you create a credential, its private key (a JSON Web Key) is returned only at creation time, and you can't view it again later. Copy it immediately and store it securely.

Using the CLI

evroc iam serviceaccount credential create ci-deploy-cred-1 \
  --service-account ci-deploy

A credential's expiration time is mandatory. The minimum is 24 hours and the maximum is 2 years. If you don't pass --expires-in, the credential defaults to 1 year:

# 90-day credential
evroc iam serviceaccount credential create ci-deploy-cred-1 \
  --service-account ci-deploy --expires-in 2160h

The credential's default type is rs256-jwt. When you create a credential, the CLI prints the private key. Capture it before the command returns.

To create a credential for the S3 compatible API, pass --type hmac-sigv4:

evroc iam serviceaccount credential create storage-ingest-cred-1 \
  --service-account storage-ingest --type hmac-sigv4

When you create an hmac-sigv4 credential, the access key ID and secret access key are returned in the response. Copy them immediately and store them securely.

Using the console

From the service account's page in the Console, create a credential. When the credential is created, the Console shows a dialog that reminds you the private key can't be viewed again. Copy the private key (and the credential ID) before you close the dialog.

HMAC credentials (hmac-sigv4) are not yet available through the Console. To create an HMAC credential, use the CLI command shown above.

Use the credential

Store the credential's private key where the workload can read it. A common approach is to set it as an environment variable. The evroc Go SDK, for example, reads the service account ID and the private key from the environment:

export EVROC_SERVICE_ACCOUNT_ID="ci-deploy"
export EVROC_SERVICE_ACCOUNT_SECRET="*** private key"

Grant access

Creating a service account and a credential doesn't give it any access yet. Grant the roles the workload needs by creating a role binding that targets the service account. See fine-grained access for how roles and permissions work.

Verify and manage

List the service accounts in a project:

evroc iam serviceaccount list

Get a single service account:

evroc iam serviceaccount get ci-deploy

Disable or re-enable a service account:

evroc iam serviceaccount update ci-deploy --enabled=false

Delete a service account (this prompts for confirmation unless you pass --force):

evroc iam serviceaccount delete ci-deploy

Manage credentials

List a service account's credentials:

evroc iam serviceaccount credential list --service-account ci-deploy

Revoke a credential when you suspect it's been exposed. A reason is required:

evroc iam serviceaccount credential revoke ci-deploy-cred-1 \
  --service-account ci-deploy --reason "Compromised"

Delete a credential:

evroc iam serviceaccount credential delete ci-deploy-cred-1 \
  --service-account ci-deploy

Next steps