> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage users in SUNK

> Enable automatic user provisioning for SUNK with nsscache

SUNK User Provisioning (SUP) uses [nsscache](https://github.com/google/nsscache), a lightweight directory service, to manage users across CoreWeave clusters. It supports two directory protocols: <Tooltip tip="System for Cross-domain Identity Management (SCIM) is an open standard protocol that automates user account provisioning and management across different systems." cta="Learn more" href="/glossary#system-for-cross-domain-identity-management-scim">SCIM</Tooltip> and <Tooltip tip="Lightweight Directory Access Protocol (LDAP) is a protocol for accessing and managing distributed directory information services." cta="Learn more" href="/glossary#lightweight-directory-access-protocol-ldap">LDAP</Tooltip>. We recommend SCIM, because it enables automated user and group synchronization from your upstream <Tooltip tip="An Identity Provider (IdP) is an entity that stores and verifies the identity of a user." cta="Learn more" href="/glossary#identity-provider-idp">identity provider (IdP)</Tooltip> to SUNK. When you add or remove a user in your IdP, the change appears in your SUNK cluster within minutes, keeping access accurate and up to date.

Whether your users are managed in a third-party IdP or directly in CoreWeave IAM, SUP provisions, updates, and removes POSIX users in your cluster without manual intervention.

This guide demonstrates how to configure `nsscache` to support SUP with the following steps:

1. [Set up SUNK User Provisioning (SUP)](/products/sunk/manage_sunk/manage_cluster_access/sunk_user_provisioning).
2. [Create user groups with CoreWeave IAM or your upstream IdP](/products/sunk/manage_sunk/manage_cluster_access/sunk_user_provisioning#create-sunk-user-groups).
3. [Create a Kubernetes Secret and add it to the `slurm` chart](#configure-a-kubernetes-secret-for-sup).

## Prerequisites

Before making any changes to the `nsscache` configuration, you must first do the following:

* [Set up SUP](/products/sunk/manage_sunk/manage_cluster_access/sunk_user_provisioning). SUP is required to provision cluster access to users, whether you use a federated IdP or not.
* [Create user groups with CoreWeave IAM or your upstream IdP](/products/sunk/manage_sunk/manage_cluster_access/sunk_user_provisioning#create-sunk-user-groups). SUP provisions access to groups of users, rather than individual users. You must create these groups before you configure `nsscache`, and the group names must exactly match the group names specified in the `nsscache` configuration.

## Configure a Kubernetes Secret for SUP

With prerequisites in place, give `nsscache` the credentials it needs to authenticate with your directory service. Create a Kubernetes Secret that contains the configuration for your directory service, then add the Secret to the `slurm` chart's `values.yaml` file, as detailed in the following sections.

### Create a Kubernetes Secret

Create a [Kubernetes Secret](https://kubernetes.io/docs/concepts/configuration/secret/) that contains the configuration for your directory service.

<Warning>
  CoreWeave discourages including sensitive information, such as plaintext user credentials, directly in your `values.yaml` configuration. Instead, use a Kubernetes Secret for added security and manageability. CoreWeave provides [encryption at rest](/products/cks/clusters/secrets) for `etcd` data, which includes Secrets.
</Warning>

This Secret can be a SCIM token or an LDAP service account password. Be sure to follow the appropriate naming conventions detailed in the following sections when creating your Secret.

#### Naming conventions for SCIM Secrets

For a SCIM Secret, the suggested Secret name is `[RELEASE-NAME]-nsscache-scim-secret`.

Inside the Secret, the `key` under `data` must be named `nsscache-scim-auth-token`, as shown in the following example. This contains the base64-encoded SCIM token.

```yaml theme={"system"}
apiVersion: v1
kind: Secret
metadata:
  name: scim-auth-token
data:
  nsscache-scim-auth-token: [BASE64-ENCODED-SCIM-TOKEN]
```

#### Naming conventions for LDAP Secrets

For an LDAP Secret, the suggested Secret name is `[RELEASE-NAME]-nsscache-ldap-secret`.

Inside the Secret, the `key` under `data` must be named `nsscache-ldap-password`. This contains the base64-encoded password for the LDAP service.

### Update the `slurm` chart with your Kubernetes Secret

After you create the Secret, update the `slurm` chart's `values.yaml` file so that `nsscache` references it.

Edit the `nsscache.existingSecret` parameter with the name of your Secret, as shown in [Provision cluster access to groups of users](#provision-cluster-access-to-groups-of-users). With the Secret in place and referenced from the chart, `nsscache` can authenticate against your directory service.

## Provision cluster access to groups of users

Once `nsscache` can authenticate to your directory service, configure it to provision specific users and groups into the cluster. [SUP](/products/sunk/manage_sunk/manage_cluster_access/sunk_user_provisioning) provisions cluster access to **groups of users**, rather than individual users. You must [create the groups in CoreWeave IAM or your upstream IdP](/products/sunk/manage_sunk/manage_cluster_access/sunk_user_provisioning#create-sunk-user-groups) before you configure `nsscache`. The names of your created user groups must match the group names specified in the `nsscache` configuration exactly.

```yaml title="Example SCIM values" highlight={4} theme={"system"}
sssdContainer:
  enabled: false
# You may remove the `directoryService` key when using nsscache
directoryService:
nsscache:
  enabled: true
  existingSecret: scim-auth-token
  sudoGroups:
    - slurm-admins
  nsscacheConfig:
    default:
      source: scim
      scim_base_url: https://api.coreweave.com/scim/<org>
      scim_users_parameters: filter=active eq "true"&groups=slurm-users,slurm-admins
      scim_groups_parameters: excludeInactiveUsers=true&includeVirtualUserGroups=slurm-users,slurm-admins
```

The `values.yaml` file sets the suggested `nsscache` configuration for SCIM by default. For a full list of configuration options, see the [SCIM parameter reference](/products/sunk/reference/nsscache_reference).

The following parameters configure the groups to provision:

* `sudoGroups` specifies the user groups that can run `sudo` commands in the nodes.
* `scim_users_endpoint` specifies the SCIM endpoint path for retrieving user data. The default value is `Users`.
* `scim_groups_endpoint` specifies the SCIM endpoint path for retrieving group data. The default value is `Groups`.
* `scim_users_parameters` specifies which **users** in these groups to provision, so they find their User ID in the cluster. By default, this filters out inactive users with `filter=active eq "true"`.
* `scim_groups_parameters` specifies the groups to provision. By default, this filters out inactive users with `excludeInactiveUsers=true`. If you specify no user groups, `nsscache` provisions all groups.

### Filter specific user groups

`scim_groups_parameters` and `scim_users_parameters` let you add optional parameters to the `groups` and `users` endpoints, respectively. `nsscache` automatically URL-encodes special characters such as spaces and quotes.

To provision access to specific user groups, list the group names in **both** the `scim_users_parameters` and `scim_groups_parameters` parameters, as follows:

```yaml theme={"system"}
scim_users_parameters: filter=active eq "true"&groups=slurm-users,slurm-admins
scim_groups_parameters: excludeInactiveUsers=true&includeVirtualUserGroups=slurm-users,slurm-admins
```

The previous example does the following:

* Filters out inactive users.
* Provisions access to the **users** in the `slurm-users` and `slurm-admins` groups.
* Provisions the virtual user groups `slurm-users` and `slurm-admins`.

Specify the group names exactly as they appear in your IdP, and list them in both the `scim_users_parameters` and `scim_groups_parameters` parameters so that `nsscache` provisions the users and groups correctly.

#### Example: Authentik LDAP values

```yaml title="Example Authentik LDAP values" highlight={4} theme={"system"}
sssdContainer:
  enabled: false
# Remove the `directoryService` key
directoryService:
nsscache:
  enabled: true
  existingSecret: nsscache-ldap-secret
  nsscacheConfig:
    default:
      source: ldap
      ldap_uri: ldap://authentik-outpost-ldap-outpost
      ldap_base: dc=coreweave,dc=cloud
      ldap_bind_dn: cn=ldapsvc,dc=coreweave,dc=cloud
      ldap_bind_password:
      ldap_rfc2307bis: 1
      ldap_default_shell: /bin/bash
      ldap_scope: sub
      ldap_uidattr: cn
    passwd:
      ldap_filter: (objectClass=user)
      ldap_override_home_dir: /mnt/home/%%u
    group:
      ldap_filter: (objectClass=group)
    shadow:
      ldap_filter: (objectClass=user)
    sshkey:
      ldap_filter: (objectClass=user)
```

## Verify and troubleshoot `nsscache`

After you configure `nsscache`, use the following checks to confirm that user and group data is syncing from your directory service into the cluster.

You don't need to sync data manually with `nsscache`. It takes about two minutes for data to sync from an identity provider to SUNK through `nsscache`. If user data isn't available, wait a few minutes and check again.

To validate that `nsscache` is working, follow these steps:

1. Log in to the Login pod for your cluster.

   ```bash theme={"system"}
   kubectl exec -it [LOGIN-POD] -c sshd -- /bin/bash
   ```

2. Access the `/etc/nsscache` directory and list the files within:

   ```bash theme={"system"}
   cd /etc/nsscache && ls
   ```

   This should return the following files:

   ```text theme={"system"}
   group.cache passwd.cache shadow.cache sshkey.cache
   ```

3. Check the contents of the `group.cache`, `passwd.cache`, `shadow.cache`, and `sshkey.cache` files directly for information about the users and groups in your directory, as shown with the following `cat` command:

   ```bash theme={"system"}
   cat sshkey.cache
   ```

   Alternatively, use the `getent` command with the `group`, `passwd`, or `shadow` options to list the system users and groups in addition to the data pulled by `nsscache`, as shown in the following example:

   ```bash theme={"system"}
   getent passwd
   ```

   The `getent` command doesn't retrieve SSH keys directly. To view the contents of the `sshkey.cache` file, use the `cat` command, as shown in the preceding example.

## Migrate to `nsscache` from SSSD

<Note>
  In SUNK v7.0.0 and later, `nsscache` is the default directory service. The following steps only apply if you use an earlier version of SUNK and are migrating to `nsscache` for your directory service.
</Note>

If you're upgrading from an earlier version of SUNK that used SSSD, the following sections describe how to disable SSSD and switch the relevant Helm charts to `nsscache`.

### Disable SSSD in the `slurm` and `slurm-login` charts

SSSD and `nsscache` are mutually exclusive, so you must turn off SSSD before `nsscache` can handle directory lookups. To enable `nsscache`, you must edit the `slurm` Helm chart. If you use [individual login pods](/products/sunk/deploy_sunk/configure-slurm-individual-login), you must also edit the `slurm-login` Helm chart.

### Update the `slurm` chart

In the `slurm` chart's `values.yaml` file, update the `sssdContainer.enabled` parameter to `false` and remove the `directoryService` section, as shown in the following example:

```yaml highlight={4} theme={"system"}
sssdContainer:
  enabled: false
# Remove the `directoryService` key
directoryService:
```

This disables SSSD, which is incompatible with `nsscache`.

You may remove the `directoryCache.directoryService` section in the `values.yaml` of the `slurm` chart, because `nsscache` does not use this configuration.

<Note>
  **Disable SSSD**

  You must disable SSSD to use `nsscache`. For SUNK versions v6.x and earlier, SSSD is enabled by default.
</Note>

### Update the `slurm-login` chart

If you use [individual login pods](/products/sunk/deploy_sunk/configure-slurm-individual-login), you must also edit the `slurm-login` chart's `values.yaml` file.

Set the `directoryCache.source` parameter to `nsscache`, as shown in the following example:

```yaml highlight={4} theme={"system"}
directoryCache:
  source: nsscache
# Remove the `directoryService` key
  directoryService:
```

You may remove the `directoryCache.directoryService` section in the `values.yaml` of the `slurm-login` chart, because `nsscache` does not use this configuration.

At this point, both the `slurm` and `slurm-login` charts are configured to use `nsscache` as the directory service, and your cluster is ready to provision users through SUP.