1. StreamNative Cloud
  2. Managed access

Work with service accounts

Service accounts are created for automation purposes, such as to authenticate bots that operate on your organization.

Work with service accounts through snctl

In this section, the organization has the name matrix as an example name.

Create a service account through snctl

To create a service account through snctl, follow these steps.

  1. Define a service account resource named bot by using a manifest file and save the manifest file sa-bot.yaml.

    apiVersion: cloud.streamnative.io/v1alpha1
    kind: ServiceAccount
    metadata:
      namespace: matrix
      name: bot
    

    The following table lists fields in the manifest file.

    FieldDescription
    apiVersionSpecify the version of Pulsar API server.
    kindSpecify the component to be created.
    metadataConfigure the metadata information about the service account.
    - namespace: specify the name of the organization.
    - name: specify the name of the service account.
  2. Apply the manifest file to create the service account.

    snctl apply -f /path/to/sa-bot.yaml
    

    Output

    serviceaccount.cloud.streamnative.io/bot created
    
  3. Check whether the service account was created successfully.

    snctl describe serviceaccount bot
    

    Output

    Name:         bot
    Namespace:    matrix
    Labels:       <none>
    Annotations:  <none>
    API Version:  cloud.streamnative.io/v1alpha1
    Kind:         ServiceAccount
    Metadata:
      Creation Timestamp:  2020-08-11T16:25:10Z
      Finalizers:
        serviceaccount.finalizers.cloud.streamnative.io
      Generation:        1
      Resource Version:  396516
      Self Link:         /apis/cloud.streamnative.io/v1alpha1/namespaces/matrix/serviceaccounts/bot
      UID:               874b226b-ea01-41c2-9a7b-059fdcc0d5c1
    Spec:
    Status:
      Conditions:
        Last Transition Time:  2020-08-14T06:25:52Z
        Reason:                Provisioned
        Status:                True
        Type:                  Ready
      Private Key Data:
      Private Key Type:        TYPE_SN_CREDENTIALS_FILE
    Events:                    <none>
    

    From the output, you can see that the status and type parameters for items under Conditions are set to true and ready. This means that the service account bot was created successfully.

In addition, you can use the snctl create serviceaccount SERVICE_ACCOUNT_NAME command to create a service account. For details, see snctl reference.

Download service account credentials

To use a service account, you first download its associated credentials to a JSON file. The information is made available through the status block of the ServiceAccount resource.

The following example shows how to download the service account credentials to a file called bot.json.

snctl auth export-service-account bot --key-file bot.json

The file contents will be similar to the following:

{
  "type": "SN_SERVICE_ACCOUNT",
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "client_email": "[email protected]"
}

The following table lists two fields in the JSON file.

FieldDescription
client_idIt is an Auth0 Application that has been created.
client_secretIt is used to authenticate to Auth0 for accessing snctl.

The file contains credentials information and should be well protected.

Activate a service account

This example shows how to activate a service account through a key file called bot.json.

snctl auth activate-service-account --key-file bot.json -a https://api.streamnative.cloud -i https://auth.streamnative.cloud/

Output

Logged in as [email protected]
Welcome to StreamNative Cloud!

Access the StreamNative Cloud API

This example shows how to access the StreamNative Cloud API through a service account.

  1. Log in to snctl.

    snctl auth login
    
  2. Create a service account.

    This example creates a service account named bot.

    snctl create serviceaccount bot.
    

    Output

    serviceaccount.cloud.streamnative.io/bot created
    
  3. Download the associated credentials of the service account to a JSON file。

    snctl auth export-service-account bot -f bot.json
    

    Output

    Wrote private key file 'bot.json'.
    
  4. Bind the service account with an "admin" role.

    snctl create rolebinding bot-cluster-admin --role admin --serviceaccount bot
    

    Output

    rolebinding.cloud.streamnative.io/bot-cluster-admin created
    
  5. Log out from snctl.

    snctl auth logout
    
  6. Log in to snctl with the service account.

    snctl auth activate-service-account --key-file bot.json
    

    Output

    Logged in as [email protected]
    Welcome to StreamNative Cloud!
    

Connect to a Pulsar cluster

This example shows how to connect to a Pulsar cluster by using a service account.

  1. Log in to snctl.

    snctl auth login
    
  2. Create a service account.

    This example creates a service account named bot.

    snctl create serviceaccount bot.
    

    Output

    serviceaccount.cloud.streamnative.io/bot created
    
  3. Download the associated credentials of the service account to a JSON file。

    snctl auth export-service-account bot -f bot.json
    

    Output

    Wrote private key file 'bot.json'.
    
  4. Connect to a Pulsar cluster using the pulsarctl. Replace the YOUR-KEY-FILE-PATH parameter with the local path for the downloaded JSON file. For details about connecting to a Pulsar cluster through other Pulsar CLI tools, see connect.

    pulsarctl namespaces list public \
        --admin-service-url https://neo1.matrix.us-east4.streamnative.g.snio.cloud \
        --issuer-endpoint https://streamnative.cloud \
        --client-id abcdefghigk0123456789 \
        --audience urn:sn:pulsar:pulsar-instance-ns:pulsar-instance-name \
        --key-file YOUR-KEY-FILE-PATH
    

Check service accounts through snctl

This example shows how to check the service accounts of an organization.

snctl get serviceaccount

Output

NAME   CREATED AT
bot   2020-08-11T16:25:10Z

From the output of this command, you can see all created service accounts and the time when these service accounts were created.

Check service account details through snctl

Before checking the details about a service account, you should use the following command to confirm whether the service account is available.

snctl get serviceaccount

Then, you can use the following command to check details about a service account.

snctl describe serviceaccount SERVICE_ACCOUNT_NAME

The following example checks the details about the service account bot.

snctl describe serviceaccount bot

Output

Name:         bot
Namespace:    matrix
Labels:       <none>
Annotations:  <none>
API Version:  cloud.streamnative.io/v1alpha1
Kind:         ServiceAccount
Metadata:
  Creation Timestamp:  2020-08-11T16:25:10Z
  Finalizers:
    serviceaccount.finalizers.cloud.streamnative.io
  Generation:        1
  Resource Version:  396516
  Self Link:         /apis/cloud.streamnative.io/v1alpha1/namespaces/matrix/serviceaccounts/bot
  UID:               874b226b-ea01-41c2-9a7b-059fdcc0d5c1
Spec:
Status:
  Conditions:
    Last Transition Time:  2020-08-14T06:25:52Z
    Reason:                Provisioned
    Status:                True
    Type:                  Ready
  Private Key Data:
  Private Key Type:        TYPE_SN_CREDENTIALS_FILE
Events:                    <none>

Delete a service account through snctl

You can use the following command to delete a service account based on the service account name.

snctl delete serviceaccount SERVICE_ACCOUNT_NAME

In addition, you can use the following command to delete the service account based on the name specified in the manifest file.

snctl delete -f ./sa-bot.yaml

Work with a service account through StreamNative Cloud Console

This section describes how to work with a service account through the StreamNative Cloud Console.

Currently, you can't edit a service account. If you need a service account to have Super Admin access, make sure to enable this feature when creating the service account. Service accounts do not have Super Admin enabled by default.

Create a service account through StreamNative Cloud Console

To create a service account, follow these steps.

  1. On the left navigation pane, click Service Accounts.

  2. Click Create Service Account. A dialog box displays.

    screenshot of a dialog box with a texbox for entering the service account name

  3. (Optional) Select Super Admin to grant the service account access to a namespace or tenant.

  4. Enter a name for the service account, and then click Confirm.

Check service account details

After you have created a service account, you can check the details of the account.

  • On the left navigation pane, click Service Accounts. The Service Accounts page displays all of the created service accounts.

The table below describes the details that you can view about the service account.

ItemDescription
NameThe name of the service account.
Pulsar Role NameThis name displays in the Admin Role field when creating a tenant.
Key FileThe key file for the service account.
TokenThe token for the service account.
OrganizationThe organization that the service account was created in.
Create TimeThe time when the service account was created.
StatusThe status of the service account.
AdminWhether the service account has Super Admin enabled or not.
...Click the ellipsis to display the delete icon.

Get the service account key file or token

Both the key file and the token are used for authentication. Tokens are only valid for seven days. When a token expires, you need to use the key file to generate a new token for authentication. Or, you can directly use the key file for authentication.

To get the key file or token of a service account, follow these steps.

  1. On the left navigation pane, click Service Accounts.

  2. Get the key file or the token.

    • In the row of the service account you want to use, in the Key File column, click the Download icon to download the key file to your local directory.

    • In the row of the service account you want to use, in the Token column, click Generate new token, then click expires in 7 days to copy the token to your clipboard.

Delete a service account

To delete a service account, follow these steps.

  1. On the left navigation pane, click Service Accounts.

  2. Click the ellipsis at the end of the row of the service account you want to delete, and then select Delete.

    screenshot showing the ellipsis at the end of the service account details row

  3. On the dialog box asking, Are you sure you want to delete this service account?, click Confirm.

Previous
Work with topic