Service accounts are the accounts that workloads or services use to programmatically consume resources and access microservices securely. They are a special kind of identity used by an application or workload rather than by a person. Similar to a user account, service accounts can be granted permissions and roles but they can't sign in like a human user.
Service accounts are useful for managing Google Distributed Cloud (GDC) air-gapped appliance infrastructure, such as:
- Internal GDC air-gapped appliance services and workloads to securely access GDC air-gapped appliance control plane application programming interface (API).
- Customer workloads in GDC air-gapped appliance to access GDC air-gapped appliance services and make authorized application programming interface (API) calls.
- External workloads to federate with GDC air-gapped appliance.
- GDC air-gapped appliance services or system controllers to securely access customer resources. For example, service accounts can manage authentication and authorization workflows where the service controllers running in the bare metal Kubernetes cluster must run workloads managed by customers.
You can manage accounts by using the GDC console, the
gdcloud CLI, or the API. With the gdcloud CLI, the service
identity feature is built upon the ProjectServiceAccount
API.
Before you begin
You can create service accounts only within a project. For more information, see Create a project.
Create a service identity
To get the permissions required to create service accounts, ask your
Project IAM Admin to grant you the Project IAM Admin (project-iam-admin
)
role.
Users with access to service accounts can access all service accounts within a project.
To create service identities in a project, use the GDC console, the gdcloud CLI, or the API.
Console
- Sign in to the GDC console.
- In the navigation menu, select Identity & Access > Service identities.
- Click Create Service Identity. The Service Identity details page opens.
- In the Service identity name field, enter a name for your service
identity. For example:
Test service identity
. - Click Create.
gdcloud
Create a service identity:
gdcloud iam service-accounts create NAME \
--project=PROJECT
Replace the following values:
- NAME: the name of the
ProjectServiceAccount
. The name must be unique within the project namespace. - PROJECT: the project to create the service
identity in. If
gdcloud init
is already set, omit the--project
flag.
This command creates a ProjectServiceAccount
in the project namespace.
API
Create a
ProjectServiceAccount
custom resource YAML file, such asmy-project-sa.yaml
:apiVersion: resourcemanager.gdc.goog/v1 kind: ProjectServiceAccount metadata: name: NAME namespace: PROJECT spec: keys: - algorithm: ALGORITHM id: KEY_ID key: BASE64_ENCODED_KEY validAfter: "START_TIME" validBefore: "EXPIRATION_TIME"
Replace the following variables:
NAME
: the name of theProjectServiceAccount
resource. The name must be unique within the project namespace.PROJECT
: the project to create the service identity in.ALGORITHM
: the algorithm of the key. Only ES256 keys are supported.KEY_ID
: the unique identifier of the key. The ID is used to determine which key to verify against.BASE64_ENCODED_KEY
: the base64-encoded public key in PEM format to verify against. The private key used to generate this public key is expected in ECDSA P256 PEM format.START_TIME
: the start time when the key becomes valid, such as2025-02-07T00:59:34Z
.EXPIRATION_TIME
: the expiration time for the key, such as2026-02-07T00:59:34Z
.
Apply the
ProjectServiceAccount
custom resource to the management API server:kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG apply -f my-project-sa.yaml
Replace the
MANAGEMENT_API_SERVER_KUBECONFIG
variable with the path to the kubeconfig file for the management API server.
View service identities
To view a list of service accounts in a project, use the GDC console or the gdcloud CLI.
Console
- Sign in to the GDC console.
- Select a project.
- In the navigation menu, click Identity & Access > Service Identities to view the list of service accounts for the project.
gdcloud
List the service accounts in a project:
gdcloud iam service-accounts list \
--project=PROJECT
Assign a role binding to the service identity
To assign a role binding, you must have the proper permissions. To get the
permissions required to assign roles, ask your Project IAM Admin to grant
you the Project IAM Admin (project-iam-admin
) role.
Use either the GDC console or the gdcloud CLI to assign a role binding.
Console
- Sign in to the GDC console.
- Select a project.
- In the navigation menu, select Identity & Access > Access.
- In the Member list, click Add member. You see the Users and roles page.
- Select Service identity in the Member type list.
- In the Service identity list, select the service identity you want to assign a role binding.
- In the Role list, select the role that you want to assign to the service identity, such as Backup Creator.
- Optional: To add another role, click Add another role. Select the additional role.
- Click Add.
gdcloud
This command creates and names the project role binding to bind the
specified role with the ProjectServiceAccount
:
gdcloud iam service-accounts add-iam-policy-binding \
--project=PROJECT \
--role=ROLE \
--iam-account=NAME
Replace the following values:
- PROJECT: the project to create the role binding
in.
If
gdcloud init
is already set, then you can omit the--project
flag. - ROLE: the predefined role to assign to the
ProjectServiceAccount
. Specify roles in the formatRole/name
where Role is the Kubernetes type, such asRole
orProjectRole
, and name is the name of the predefined role. For example, to assign the Project Viewer role, set the role toRole/project-viewer
. - NAME: the name of the service identity to use.
Delete a service identity
To delete service accounts in a project, use theGDC console or the gdcloud CLI.
After you delete a service identity, applications don't have access to project resources through that service identity.
Console
- Sign in to the GDC console.
- In the navigation menu, select Identity & Access > Service Identities.
- Select the checkbox of the service identity that you want to delete.
- Click Delete.
- The confirmation dialog appears. In the
Confirm by typing the following below field, enter
remove
. - Click Delete.
gdcloud
Run the following command to delete a service identity:
gdcloud iam service-accounts delete NAME \
--project=PROJECT
Create and add key pairs
To create and add key pairs in a project, use the GDC console, the gdcloud CLI, or the API.
Console
- Sign in to the GDC console.
- In the navigation menu, select Identity & Access > Service Identities.
- Click the name of the service identity you want to add in the key.
- Click Create New Key.
- The new key appears in the Keys list, and a dialog confirms you've created the key successfully.
gdcloud
The gdcloud
command creates the application default credentials JSON file
and the public and private key pairs:
gdcloud iam service-accounts keys create APPLICATION_DEFAULT_CREDENTIALS_FILENAME \
--project=PROJECT \
--iam-account=NAME \
--ca-cert-path=CA_CERTIFICATE_PATH
Replace the following values:
- APPLICATION_DEFAULT_CREDENTIALS_FILENAME: the name of the JSON file.
- PROJECT : selects the project to create the key for.
If
gdcloud init
is already set, then you can omit the--project
flag. - NAME: the name of the service identity to add the key for.
- CA_CERTIFICATE_PATH: Optional: the certificate authority (CA) certificate path to verify the authentication endpoint. If you do not specify this path, the system CA certificates are used. You must install the CA in the system CA certificates.
GDC air-gapped appliance adds the public key to the ProjectServiceAccount
keys you use to verify the JSON web tokens (JWT) the private key signs. The
private key writes to the application default credentials JSON file.
The following example shows the application default credentials JSON file:
{
"type": "gdch_service_account",
"format_version": "1",
"project": "project_name",
"private_key_id": "abcdef1234567890",
"private_key": "-----BEGIN PRIVATE KEY-----\nETC\n-----END PRIVATE KEY-----\n",
"name": "service_identity_name",
"ca_cert_path": "service_identity_name",
"token_uri": "https://service-identity.<Domain>/authenticate"
}
This example uses the following values:
project
: the project namespace in the organization.private_key_id
: the ID assigned to the key.private_key
: the ECDSA P256 private key in PEM format that the CLI generates.name
: the name of the service identity.token_uri
: the address of the authentication endpoint.
API
Generate the public and private key pair. The following commands use
openssl
as an example, which is a common tool for this purpose.openssl ecparam -name prime256v1 -genkey -noout -out "key.pem" openssl ec -in "key.pem" -pubout > "pub.pem"
Base64 encode the public key and retrieve its key ID:
KEY_ID=$(openssl pkey -in key.pem -pubout -outform der | openssl dgst -sha256 | sed 's/^.* //') BASE64_ENCODED_KEY=$(cat pub.pem | base64)
Create or update the
ProjectServiceAccount
custom resource YAML file, including the generated key information from the previous step:apiVersion: resourcemanager.gdc.goog/v1 kind: ProjectServiceAccount metadata: name: NAME namespace: PROJECT spec: keys: - algorithm: ALGORITHM id: KEY_ID key: BASE64_ENCODED_KEY validAfter: "START_TIME" validBefore: "EXPIRATION_TIME"
Replace the following variables:
NAME
: the name of theProjectServiceAccount
resource. The name must be unique within the project namespace.PROJECT
: the project in which you're creating the key.ALGORITHM
: the algorithm of the key. Only ES256 keys are supported.KEY_ID
: the unique identifier of the key. The ID is used to determine which key to verify against.BASE64_ENCODED_KEY
: the base64-encoded public key in PEM format to verify against. The private key used to generate this public key is expected in ECDSA P256 PEM format.START_TIME
: the start time when the key becomes valid, such as2025-02-07T00:59:34Z
.EXPIRATION_TIME
: the expiration time for the key, such as2026-02-07T00:59:34Z
.
Apply the
ProjectServiceAccount
custom resource to the management API server:kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG apply -f my-project-sa.yaml
Replace the
MANAGEMENT_API_SERVER_KUBECONFIG
variable with the path to the kubeconfig file for the management API server.Create the application default credentials JSON file containing the private key. Make sure that the
KEY_ID
variable in the JSON file is set to the same value as theKEY_ID
variable you used in theProjectServiceAccount
spec.cat <<EOF > "key_file.json" { "format_version": "1", "name": "NAME", "private_key": "$(tr '\n' '\t' < "key.pem" | sed 's/\t/\\n/g')", "private_key_id": "KEY_ID", "project": "PROJECT", "token_uri": "AUTH_URL", "type": "gdch_service_account" } EOF
Replace the following variables:
NAME
: the name of the service identity.KEY_ID
: the unique identifier of the key. The ID is used to determine which key to verify against, and it must match theKEY_ID
value used in theProjectServiceAccount
spec.PROJECT
: the project namespace in the organization.AUTH_URL
: the address of the authentication endpoint.
Add the key pair to your project by activating the service account:
gdcloud auth activate-service-account –-key-file=key_file.json
List credentials for service accounts
List the public keys from a specific ProjectServiceAccount
in the
project:
gdcloud iam service-accounts keys list \
--project=PROJECT \
--iam-account=NAME
Delete credentials
To delete the public key, use the GDC console or the gdcloud CLI.
Console
- Sign in to the GDC console.
- In the navigation menu, select Identity & Access > Service Identities.
- Click the name of the service identity that has the key you want to delete.
- Click Delete.
- In the confirmation dialog, click Delete.
gdcloud
Remove the public key with the key ID from the specific ProjectServiceAccount
in the project:
gdcloud iam service-accounts keys delete KEY_ID \
--project=PROJECT \
--iam-account=NAME
Authorize a service account using a service account key
You can use the gdcloud
command to activate a service account using a service
account key:
Create a service account key file, if you don't already have one.
Activate the service account by running the following command:
gdcloud auth activate-service-account --key-file=KEY_FILE
Replace KEY_FILE with the path to the service account key file.
After activating the service account,
gdcloud
uses the service account's credentials for subsequent commands, instead of your user credentials.