Skip to content

ABCI Singularity Endpoint

Overview

ABCI Singularity Endpoint provides a singularity container service available within ABCI. This service consists of Remote Builder for remotely building container images using SingularityPRO and Container Library for storing and sharing the created container images. This service is available only within ABCI and cannot be accessed directly from outside of ABCI.

The following describes the basic operations for using this service in ABCI. See Sylabs Document for more information.

Preparation

Loading environment module

In order to use this service, load the module of SingularityPRO as follows.

[username@es1 ~]$ module load singularitypro

Creating Access Token

Note

Due to an update to the ABCI Singularity endpoint, access tokens obtained before March 2023 are no longer available. Therefore, after obtaining the access token again, register the access token.

You need to obtain an access token to authenticate your requests. The access token can be created by using the get_singularity_token command on the interactive node with your ABCI password, which is used to log in to ABCI User Portal.

[username@es1 ~]$ get_singularity_token
ABCI portal password :
just a moment, please...
  (The generated access token will be displayed.)

Keep your access token in a safe place for a later registration step.

Note

The access token is a very long single line of text, so be careful not to include unnecessary characters such as newlines.

Checking remote endpoint

To check that ABCI Singularity Endpoint (cloud.se2.abci.local) is correctly configured as a remote endpoint, use singularity remote list command.

[username@es1 ~]$ singularity remote list

NAME         URI                   DEFAULT?  GLOBAL?  EXCLUSIVE?  SECURE?
ABCI         cloud.se2.abci.local                               
SylabsCloud  cloud.sylabs.io                                     
[username@es1 ~]$

Note

In the output of the singularity remote list command, depending on the terminal you are using, each column contains a ? symbol may appear. In that case, ? mark to a check mark.

Note

SylabsCloud is a public service endpoint operated by Sylabs. It is available by signing in to https://cloud.sylabs.io/ and obtaining an access token.

Note

Singularity container images can also be retrieved using the Singularity Global Client. For details, refer to Singularity Global Client.

Registering Access Token

To register the access token obtained above with your configuration, use singularity remote logincommand for ABCI Singularity Endpoint.

[username@es1 ~]$ singularity remote login ABCI
Generate an access token at https://cloud.se2.abci.local/auth/tokens, and paste it here.
Token entered will be hidden for security.
Access Token:
INFO:    Access Token Verified!
INFO:    Token stored in /home/username/.singularity/remote.yaml
[username@es1 ~]$

When you have created an access token again, use the above command to register it. The old access token is overwritten by the new one.

Note

The validity period of access tokens is one year.

Remote Builder

First, create a definition file to build a container image. The following example defines installation of additional packages to the container image and commands to be executed when the container image is run, based on Ubuntu container image from Docker Hub. For more information about definition files, see Definition Files.

[username@es1 ~]$ vi ubuntu.def
[username@es1 ~]$ cat ubuntu.def
Bootstrap: docker
From: ubuntu:18.04

%post
    apt-get update
    apt-get install -y lsb-release

%runscript
    lsb_release -d

[username@es1 ~]$ 

Next, to create the container image "ubuntu.sif" by Remote Build with "ubuntu.def", specify --remote to the command singularity build.

[username@es1 ~]$ singularity build --remote ubuntu.sif ubuntu.def
INFO:    Remote "cloud.se2.abci.local" added.
INFO:    Access Token Verified!
INFO:    Token stored in /root/.singularity/remote.yaml
INFO:    Remote "cloud.se2.abci.local" now in use.
INFO:    Starting build...
:
:
INFO:    Build complete: ubuntu.sif
[username@es1 ~]$ 

You can run the container image with singularity run command as follows:

[username@es1 ~]$ qrsh -g grpname -l rt_C.small=1 -l h_rt=1:00:00
[username@g0001 ~]$ module load singularitypro
[username@g0001 ~]$ singularity run ubuntu.sif
Description:    Ubuntu 18.04.6 LTS
[username@g0001 ~]$ 

The lsb_release -d command specified in the definition file is executed and the result is printed.

Container Library (Experimental)

You can push your container images to Container Library and make those available to other ABCI users. Each user can store up to a total of 100 GiB.

Note

There is no access control function for the container images pushed to Container Library. This means that anyone who uses ABCI will be able to access them, so make sure the container images are appropriate.

Creating and Registering Signing Keys for a Container Image

To push a container image to Container Library and publish it in ABCI, create a key pair and register the public key in Keystore.The author of the container image can sign the container image using the private key, and the user of the container image can verify the signature using the public key registered in Keystore.

Creating Key Pairs

To create key pairs, use singularity key newpair command.

[username@es1 ~]$ singularity key newpair
Enter your name (e.g., John Doe) : 
Enter your email address (e.g., john.doe@example.com) : 
Enter optional comment (e.g., development keys) : 
Enter a passphrase : 
Retype your passphrase :
Would you like to push it to the keystore? [Y,n] 
Generating Entity and OpenPGP Key Pair... done

Each input value is described as follows:

item value
Enter your name Enter the ABCI account name.
Enter your email address Although it says email address, enter the ABCI account name.
Enter optional comment Enter comments you want to attach to this key pair.
Enter a passphrase Determine your passphrase and enter it. It is going to be necessary when signing a container image.
Would you like to push it to the keystore? Enter Y to upload the public key to Keystore.

Listing Keys

To retrieve information about the public keys in your local keyring, including ones you created, use singularity key list.

[username@es1 ~]$ singularity key list
Public key listing (/home/username/.singularity/sypgp/pgp-public):
:
:
   --------
7) U: username (comment) <username>
   C: 2020-06-15 03:40:05 +0900 JST
   F: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   L: 4096
   --------
[username@es1 ~]$

To retrieve key information registered in Keystore, specify the ABCI account in singularity key search -l.

[username@es1 ~]$ singularity key search -l username
Showing 1 results

FINGERPRINT                               ALGORITHM  BITS  CREATION DATE                  EXPIRATION DATE  STATUS     NAME/EMAIL
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY  RSA        4096  2020-06-15 03:40:05 +0900 JST  [ultimate]       [enabled]  username (comment) <username>

[username@es1 ~]$

Registering a Public Key in Keystore

If you did not specify the option to upload a public key to Keystore, you can upload it later.

Warning

Public keys registered in Keystore cannot be deleted.

[username@es1 ~]$ singularity key list
0) U: username (comment) username
   C: 2020-08-08 04:28:35 +0900 JST
   F: ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
   L: 4096
   --------

To upload this public key number 0, specify the fingerprint shown in F as the singularity key push.

[username@es1 ~]$ singularity key push ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
public key `ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ' pushed to server successfully

[username@es1 ~]$ singularity key search -l username
Showing 1 results

FINGERPRINT                               ALGORITHM  BITS  CREATION DATE                  EXPIRATION DATE  STATUS     NAME/EMAIL
ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ  RSA        4096  2020-06-15 03:40:05 +0900 JST  [ultimate]       [enabled]  username (comment) <username>

Getting Public Keys Registered in Keystore

Public keys registered in Keystore can be downloaded and stored in your keyring. The following example downloads and saves the public key found by searching for username2. You can also search for a string that matches the comment attached to the key. The last parameter of singularity key pull AAAA.... is a fingerprint to specify which public key to download.

[username@es1 ~]$ singularity key search -l username2
Showing 2 results

FINGERPRINT                               ALGORITHM  BITS  CREATION DATE                  EXPIRATION DATE  STATUS     NAME/EMAIL
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA  RSA        4096  2020-06-22 11:51:45 +0900 JST  [ultimate]       [enabled]  username2 (comment) <username2>

[username@es1 ~]$ singularity key pull AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
1 key(s) added to keyring of trust /home/username/.singularity/sypgp/pgp-public
[username@es1 ~]$ singularity key list
:
:
1) U: username2 (comment) <username2>
   C: 2020-08-10 11:51:45 +0900 JST
   F: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
   L: 4096
   --------
[username@es1 ~]$

Deleting Keys

You can remove a public key from your keyring by specifying a key fingerprint using singularity key remove command. Public keys registered in Keystore cannot be deleted.

[username@es1 ~]$ singularity key remove AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA

Uploading Container Images

Before uploading a container image to Container Library, sign the container image. Check the key number by using the singularity key list -s command, and sign the container by using the singularity sign command with the -k option to specify the key number. The following example uses the second key to sign ubuntu.sif.

[username@es1 ~]$ singularity key list -s
Public key listing (/home/username/.singularity/sypgp/pgp-secret):
:
:
   --------
2) U: username (comment) <username>
   C: 2020-06-15 03:40:05 +0900 JST
   F: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   L: 4096
   --------
[username@es1 ~]$ singularity sign -k 2 ./ubuntu.sif
Signing image: ./ubuntu.sif
Enter key passphrase : 
Signature created and applied to ./ubuntu.sif

The location of container images in Container Library is represented by a URI library://username/collection/repository:tag. Refer to the description of each component below to determine the URI.

item value
username Specifies your ABCI account
collection Specify collection name as any string
repository Specify the repository name as any string.
tag A string identifying the same container image. A string such as version, release date, revision number or latest.

Here is an example of uploading the container image ubuntu, specifying the collection name abci-lib and the tag name latest:

[username@es1 ~]$ singularity push ubuntu.sif library://username/abci-lib/ubuntu:latest
INFO:    Container is trusted - run 'singularity key list' to list your trusted keys
 35.36 MiB / 35.36 MiB [===========================================================================================================================================================================================================] 100.00% 182.68 MiB/s 0s
[username@es1 ~]$

Downloading Container Images

The container image uploaded to Container Library can be downloaded as follows:

[username@es1 ~]$ singularity pull library://username/abci-lib/ubuntu:latest
INFO:    Downloading library image
 35.37 MiB / 35.37 MiB [=============================================================================================================================================================================================================] 100.00% 353.47 MiB/s 0s
INFO:    Download complete: ubuntu_latest.sif
[username@es1 ~]$

If the signature cannot be verified, you will see a warning message similar to the following, but the download will continue.

WARNING: Skipping container verification

You can also use singularity verify to verify the signature after downloading it. The following example validates the signature with the public key that is registered in Keystore. The output is LOCAL rather than REMOTE if it is verified with the public key registered in your keyring. If it cannot be verified, a WARNING message is printed.

[username@es1 ~]$ singularity verify ubuntu_latest.sif
Verifying image: ubuntu_latest.sif
[REMOTE]  Signing entity: username (comment) <username>
[REMOTE]  Fingerprint: BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB
Objects verified:
ID  |GROUP   |LINK    |TYPE
------------------------------------------------
1   |1       |NONE    |Def.FILE
2   |1       |NONE    |JSON.Generic
3   |1       |NONE    |FS
Container verified: ubuntu_latest.sif

Note

You can still run the container image if validation fails, but it is recommended that you use a verifiable container image.

Searching Container Images

To search for container images uploaded to Container Library by keyword, use singularity search.

[username@es1 ~]$ singularity search hello
No users found for 'hello'

No collections found for 'hello'

Found 1 containers for 'hello'
    library://username/abci-lib/helloworld
        Tags: latest

Deleting Container Images

To delete a container image from Container Library, use singularity delete.

[username@es1 ~]$ singularity delete library://username/abci-lib/helloworld:latest

Note

You can delete container images such as library://username/abci-lib/helloworld:latest, which are associated with at least one tag or ID, but you can not delete container names such as library://username/abci-lib/helloworld.

Listing Container Images

You can view container image list information uploaded to the Container Library. The collection name list can be viewed with singularity enterprise get col. Specify ABCI account name as the argument.

[username@es1 ~]$ singularity enterprise get col username
ID                         Name            Num. Containers
username/tensorflow-test tensorflow-test 1
username/ubuntu-test     ubuntu-test     2
[username@es1 ~]$

The list of repositories in a collection can be viewed with singularity enterprise get rep. It takes an argument of the ID shown in singularity enterprise get col.

[username@es1 ~]$ singularity enterprise get rep username/ubuntu-test
ID                             Name    Description Images Tags Size      DownloadCount
username/ubuntu-test/ubuntu    ubuntu              1      0     64.0 MiB 3
username/ubuntu-test/ubuntu2   ubuntu2             1      0     67.0 MiB 5
[username@es1 ~]$

Container image information can be viewed with singularity enterprise get img. It takes an argument of ID shown in singularity enterprise get rep.

[username@es1 ~]$ singularity enterprise get img username/ubuntu-test/ubuntu2
ID                                                                                                     Tags              Arch  Description Size      Signed Encrypted Uploaded
username/ubuntu-test/ubuntu2:sha256.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx   [20221118 latest] amd64              67.0 MiB true   false     true
[username@es1 ~]$

Viewing Container Library Usage

You can view Container Library usage with show_container_library_usage. You must enter the ABCI password to show it.

[username@es1 ~]$ show_container_library_usage
ABCI portal password :
just a moment, please...
used(GiB) limit(GiB) num_of_repositories
3         100        6

Access Tokens

This section describes the commands related to the obtained access token.

Listing Access Tokens

You can list your access tokens with list_singularity_tokens. You must enter the ABCI password to display it.

[username@es1 ~]$ list_singularity_tokens
ABCI portal password :
just a moment, please...

Token ID: XXXXXXXXXXXXXXXXXXXXXXXX
Issued: Apr 5, 2023 at 6:55 pm JST
Expires: Apr 4, 2024 at 6:55 pm JST

Token ID: XXXXXXXXXXXXXXXXXXXXXXXX
Issued: Apr 6, 2023 at 12:14 pm JST
Expires: Apr 5, 2024 at 12:14 pm JST

Revoking the Access Token

You can revoke the access token with singularity enterprise delete token. Specify the Token ID you want to remove as an argument from the list of access tokens displayed in list_singularity_tokens command.

[username@es1 ~]$ singularity enterprise delete token <Token ID>
INFO:    Revoking token XXXXXXXXXXXXXXXXXXXXXXXX
[username@es1 list_singularity_tokens]$