Skip to content

Commit 57ec207

Browse files
mdlinvillemdlinville
authored
DOCS-974: Enhance service account documentation with licensing info and best practices (#1479)
1 parent ba74693 commit 57ec207

5 files changed

Lines changed: 91 additions & 16 deletions

File tree

‎content/en/_includes/service-account-benefits.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Key benefits of service accounts:
2+
- **No license consumption**: Service accounts do not consume user seats or licenses
3+
- **Dedicated API keys**: Secure credentials for automated workflows
4+
- **User attribution**: Optionally attribute automated runs to human users
5+
- **Enterprise-ready**: Built for production automation at scale
6+
- **Delegated operations**: Service accounts operate on behalf of the user or organization that creates them

‎content/en/guides/hosting/iam/access-management/manage-organization.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -311,12 +311,15 @@ This table lists the roles you can assign to a member of a team:
311311

312312
| Role | Definition |
313313
|-----------|---------------------------|
314-
| admin | A user who can add and remove other users in the team, change user roles, and configure team settings. |
314+
| Admin | A user who can add and remove other users in the team, change user roles, and configure team settings. |
315315
| Member | A regular user of a team, invited by email or their organization-level username by the team admin. A member user cannot invite other users to the team. |
316316
| View-Only (Enterprise-only feature) | A view-only user of a team, invited by email or their organization-level username by the team admin. A view-only user only has read access to the team and its contents. |
317-
| Service (Enterprise-only feature) | A service worker or service account is an API key that is useful for utilizing W&B with your run automation tools. If you use an API key from a service account for your team, ensure to set the environment variable `WANDB_USERNAME` to correctly attribute runs to the appropriate user. |
318317
| Custom Roles (Enterprise-only feature) | Custom roles allow organization admins to compose new roles by inheriting from the preceding View-Only or Member roles, and adding additional permissions to achieve fine-grained access control. Team admins can then assign any of those custom roles to users in their respective teams. Refer to the [custom roles announcement](https://wandb.ai/wandb_fc/announcements/reports/Introducing-Custom-Roles-for-W-B-Teams--Vmlldzo2MTMxMjQ3) for details. |
319318

319+
{{% alert color="info" %}}
320+
Service accounts are not users, but rather non-human identities used for automation. **Service accounts** provide API keys for automated workflows and do not consume user licenses. Refer to [Use service accounts to automate workflows]({{< relref "/guides/hosting/iam/authentication/service-accounts.md" >}}) for comprehensive information about creating and managing service accounts.
321+
{{% /alert %}}
322+
320323
{{% alert %}}
321324
Only enterprise licenses on Dedicated cloud or Self-managed deployment can assign custom roles to members in a team.
322325
{{% /alert %}}

‎content/en/guides/hosting/iam/authentication/service-accounts.md‎

Lines changed: 69 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,28 @@ displayed_sidebar: default
44
title: Use service accounts to automate workflows
55
---
66

7-
A service account represents a non-human or machine user that can automatically perform common tasks across projects within a team or across teams.
7+
A service account represents a non-human or machine user that can automatically perform common tasks across projects within a team or across teams. Service accounts are ideal for CI/CD pipelines, automated training jobs, and other machine-to-machine workflows.
88

9-
- An org admin can create a service account at the scope of the organization.
10-
- A team admin can create a service account at the scope of that team.
9+
## Key benefits
10+
11+
{{< readfile file="/content/en/_includes/service-account-benefits.md" >}}
12+
13+
## Overview
14+
15+
Service accounts provide a secure way to automate W&B workflows without using personal user credentials or hard-coded credentials. They can be created at two scopes:
16+
17+
- **Organization-scoped**: Created by org admins, with access across all teams.
18+
- **Team-scoped**: Created by team admins, with access limited to a specific team
1119

12-
A service account's API key allows the caller to read from or write to projects within the service account's scope.
20+
A service account's API key allows the caller to read from or write to projects within the service account's scope. This enables centralized management of automated workflows for experiment tracking in W&B Models or logging traces in W&B Weave.
1321

14-
Service accounts allow for centralized management of workflows by multiple users or teams, to automate experiment tracking for W&B Models or to log traces for W&B Weave. You have the option to associate a human user's identity with a workflow managed by a service account, by using either of the [environment variables]({{< relref "/guides/models/track/environment-variables.md" >}}) `WANDB_USERNAME` or `WANDB_USER_EMAIL`.
22+
Service accounts are particularly useful for:
23+
- **CI/CD pipelines**: Automatically log model training runs from GitHub Actions, GitLab CI, or Jenkins
24+
- **Scheduled jobs**: Nightly model retraining, periodic evaluation runs, or data validation workflows
25+
- **Production monitoring**: Log inference metrics and model performance from production systems
26+
- **Jupyter notebooks**: Shared notebooks in JupyterHub or Google Colab environments
27+
- **Kubernetes jobs**: Automated workflows running in K8s clusters
28+
- **Airflow/Prefect/Dagster**: ML pipeline orchestration tools
1529

1630
{{% alert %}}
1731
Service accounts are available on [Dedicated Cloud]({{< relref "/guides/hosting/hosting-options/dedicated_cloud.md" >}}), [Self-managed instances]({{< relref "/guides/hosting/hosting-options/self-managed.md" >}}) with an enterprise license, and enterprise accounts in [SaaS Cloud]({{< relref "/guides/hosting/hosting-options/saas_cloud.md" >}}).
@@ -59,4 +73,53 @@ A team-scoped service account cannot log runs to a [team or restricted-scoped pr
5973

6074
### External service accounts
6175

62-
In addition to **Built-in** service accounts, W&B also supports team-scoped **External service accounts** with the W&B SDK and CLI using [Identity federation]({{< relref "./identity_federation.md#external-service-accounts" >}}) with identity providers (IdPs) that can issue JSON Web Tokens (JWTs).
76+
In addition to built-in service accounts, W&B also supports team-scoped external service accounts with the W&B SDK and CLI using [Identity federation]({{< relref "./identity_federation.md#external-service-accounts" >}}) with identity providers (IdPs) that can issue JSON Web Tokens (JWTs).
77+
78+
## Best practices
79+
80+
Follow these recommendations to ensure secure and efficient use of service accounts in your organization:
81+
82+
- **Use a secrets manager**: Store service account API keys in a secure secrets management system (e.g., AWS Secrets Manager, HashiCorp Vault, Azure Key Vault) rather than in plain text configuration files.
83+
84+
- **Principle of least privilege**: Create team-scoped service accounts when possible, rather than organization-scoped accounts, to limit access to only necessary projects.
85+
86+
- **Unique service accounts per use case**: Create separate service accounts for different automation workflows (e.g., one for CI/CD, another for scheduled retraining) to improve auditability and enable granular access control.
87+
88+
- **Regular audits**: Periodically review active service accounts and remove those no longer in use. Check the audit logs to monitor service account activity.
89+
90+
- **Secure API key handling**:
91+
- Never commit API keys to version control
92+
- Use environment variables to pass keys to applications
93+
- Rotate keys if they are accidentally exposed
94+
95+
- **Naming conventions**: Use descriptive names that indicate the service account's purpose:
96+
- Good: `ci-model-training`, `nightly-eval-pipeline`, `prod-inference-monitor`
97+
- Avoid: `service-account-1`, `test-sa`, `temp`
98+
99+
- **User attribution**: When multiple team members use the same automation workflow, set `WANDB_USERNAME` or `WANDB_USER_EMAIL` to track who triggered each run:
100+
```bash
101+
export WANDB_API_KEY="<service_account_key>"
102+
export WANDB_USERNAME="john.doe@company.com"
103+
```
104+
105+
- **Environment configuration**: For team-scoped service accounts, always set the `WANDB_ENTITY` to ensure runs log to the correct team:
106+
```bash
107+
export WANDB_ENTITY="ml-team"
108+
export WANDB_PROJECT="production-models"
109+
```
110+
111+
- **Error handling**: Implement proper error handling and alerts for failed authentication to quickly identify issues with service account credentials.
112+
113+
- **Documentation**: Maintain documentation of:
114+
- Which service accounts exist and their purposes
115+
- Which systems/workflows use each service account
116+
- Contact information for the team responsible for each account
117+
118+
## Troubleshooting
119+
120+
Common issues and solutions:
121+
122+
- **"Unauthorized" errors**: Verify the API key is correctly set and the service account has access to the target project
123+
- **Runs not appearing**: Check that `WANDB_ENTITY` is set to the correct team name
124+
- **User attribution not working**: Ensure the user specified in `WANDB_USERNAME` is a member of the team
125+
- **Access denied to restricted projects**: Explicitly add the service account to the restricted project's access list

‎content/en/guides/models/app/settings-page/teams.md‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -51,14 +51,17 @@ Select a team role when you invite colleagues to join a team. There are followin
5151

5252
- **Admin**: Team admins can add and remove other admins or team members. They have permissions to modify all projects and full deletion permissions. This includes, but is not limited to, deleting runs, projects, artifacts, and sweeps.
5353
- **Member**: A regular member of the team. By default, only an admin can invite a team member. To change this behavior, refer to [Manage team settings]({{< relref "team-settings.md#privacy" >}}).
54-
55-
A team member can delete only runs they created. Suppose you have two members A and B. Member B moves a run from team B's project to a different project owned by Member A. Member A cannot delete the run Member B moved to Member A's project. An admin can manage runs and sweep runs created by any team member.
5654
- **View-Only (Enterprise-only feature)**: View-Only members can view assets within the team such as runs, reports, and workspaces. They can follow and comment on reports, but they can not create, edit, or delete project overview, reports, or runs.
5755
- **Custom roles (Enterprise-only feature)**: Custom roles allow organization admins to compose new roles based on either of the **View-Only** or **Member** roles, together with additional permissions to achieve fine-grained access control. Team admins can then assign any of those custom roles to users in their respective teams. Refer to [Introducing Custom Roles for W&B Teams](https://wandb.ai/wandb_fc/announcements/reports/Introducing-Custom-Roles-for-W-B-Teams--Vmlldzo2MTMxMjQ3) for details.
58-
- **Service accounts (Enterprise-only feature)**: Refer to [Use service accounts to automate workflows]({{< relref "/guides/hosting/iam/authentication/service-accounts.md" >}}).
56+
57+
A team member can delete only runs they created. Suppose you have two members A and B. Member B moves a run from team B's project to a different project owned by Member A. Member A cannot delete the run Member B moved to Member A's project. An admin can manage runs and sweep runs created by any team member.
58+
59+
### Service accounts
60+
61+
In addition to user roles, teams can also use **service accounts** for automation. Service accounts are not users, but rather non-human identities used for automated workflows. Refer to [Use service accounts to automate workflows]({{< relref "/guides/hosting/iam/authentication/service-accounts.md" >}}) for detailed information.
5962

6063
{{% alert %}}
61-
W&B recommends to have more than one admin in a team. It is a best practice to ensure that admin operations can continue when the primary admin is not available.
64+
W&B recommends assigning more than one admin in a team to ensure that admin operations can continue when the primary admin is not available.
6265
{{% /alert %}}
6366

6467
### Team settings

‎content/en/support/kb-articles/service_account_useful.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,13 @@ support:
88
---
99

1010

11-
A service account (Enterprise-only feature) represents a non-human or machine user, which can automate common tasks across teams and projects or ones that are not specific to a particular human user. You can create a service account within a team and use its API key to read from and write to projects within that team.
12-
13-
Among other things, service accounts are useful for tracking automated jobs logged to wandb, like periodic retraining, nightly builds, and so on. If you'd like, you can associate a username with one of these machine-launched runs with the [environment variables]({{< relref "/guides/models/track/environment-variables.md" >}}) `WANDB_USERNAME` or `WANDB_USER_EMAIL`.
11+
A **service account** represents a non-human or machine identity, which can automate common tasks across teams and projects. Service accounts are ideal for CI/CD pipelines, automated training jobs, and other machine-to-machine workflows.
1412

13+
{{< readfile file="/content/en/_includes/service-account-benefits.md" >}}
1514

15+
Among other things, service accounts are useful for tracking automated jobs logged to wandb, like periodic retraining, nightly builds, and so on. If you'd like, you can associate a username with one of these machine-launched runs with the [environment variables]({{< relref "/guides/models/track/environment-variables.md" >}}) `WANDB_USERNAME` or `WANDB_USER_EMAIL`.
1616

17-
Refer to [Team Service Account Behavior]({{< relref "/guides/models/app/settings-page/teams.md#team-service-account-behavior" >}}) for more information.
17+
For comprehensive information about service accounts, including best practices and detailed setup instructions, refer to [Use service accounts to automate workflows]({{< relref "/guides/hosting/iam/authentication/service-accounts.md" >}}). For information about how service accounts behave in team contexts, refer to [Team Service Account Behavior]({{< relref "/guides/models/app/settings-page/teams.md#team-service-account-behavior" >}}).
1818

1919
You can get the API key for a service account in your team at `<WANDB_HOST_URL>/<your-team-name>/service-accounts`. Alternatively you can go to the **Team settings** for your team and then refer to the **Service Accounts** tab.
2020

0 commit comments

Comments
 (0)