1. NGC Container Registry for DGX Overview

This document is for NVIDIA® DGX™ customers and describes how to use the enterprise functionality of the NVIDIA® GPU Cloud (NGC) container registry. This guide assumes the user is familiar with Linux and Docker, and has access to at least one DGX system configured for internat access and prepared for running NVIDIA's GPU-accelerated Docker containers (Docker and either the Docker Engine Utility for NVIDIA GPUs or the NVIDIA Container Runtime for Docker installed).

The NGC container registry for DGX offers all of the current DGX Container Registry functionality, access to additional containers, and an improved user interface. The following are some of the key areas of difference between using the DGX Container Registry and using the NGC container registry as covered in this document:

Feature DGX Container Registry NGC Container Registry for DGX
User Interface http://compute.nvidia.com http://ngc.nvidia.com
Project Registry Space URL nvcr.io/org_project/ nvcr.io/org/team
User Roles Organization Admin Organization Admin
Read-write User Team Admin
Read-only User User (all users have read-write access)

Until September 14, 2018, you can still access the DGX Container Registry by using the appropriate registry space URL format and the API Key obtained from compute.nvidia.com. See the DGX Container Registry User Guide for instructions.

1.1. About the NGC Container Registry

Docker containers simplify deployment of data center applications, such as those used for deep learning. Through the NVIDIA® GPU® Cloud (NGC) container registry, NVIDIA provides a collection of "containerized" deep learning applications that have been optimized for use with NVIDIA GPUs.

You can access NVIDIA containers from the Docker command line or through the NGC website.

For more information about NVIDIA containers and frameworks, see the NVIDIA Containers and Deep Learning Frameworks User Guide.

1.2. General Workflow for Using the NGC Container Registry

Using the NGC container registry involves accessing the NGC website and using the Docker command line, as described in this general workflow:

  1. Obtain an NGC account.
  2. Log on to the NGC website and obtain your API Key so you can access the NGC container registry.
  3. Access the NGC container registry from the Docker command line to push, pull, and run the containers.

2. NGC Container Registry Spaces and User Roles

2.1. NGC Container Registry Account Types

There are two types of NGC accounts available:

  • NGC accounts associated with the organization that purchased a DGX system.

    NVIDIA creates accounts for the initial administrators.

    If you are part of that organization, your NGC organization administrator will need to add you to the account. Once you are added, you will receive an invitation email and will be able to activate the account.

  • Personal NGC accounts

    You can also sign up for your own NGC account. To set up a personal NGC account, see Getting Started Using NVIDIA GPU Cloud for instructions.

2.2. NGC Container Registry Spaces

The following are the registry spaces available to NGC container registry for DGX users:

  • NVIDIA Repositories
    Example Paths:
    • nvcr.io/nvidia/
    • nvcr.io/hpc
    • nvcr.io/nvidia-hpsvis
    • nvcr.io/partners

    These spaces contain images provided by NVIDIA and other developers. All users can pull images from these spaces.

    NVIDIA also provides a CUDA container image within the following public repository that is available to anyone without an NGC account: nvcr.io/public

  • Enterprise Organization

    Path: nvcr.io/org/

    This space is created for a DGX customer organization during the initial NGC container registry setup.

  • Team

    Path: nvcr.io/org/team

    This space is created by the organization administrator for use by other users within their organization who have been added to the team.

2.3. NGC Container Registry User Roles

The NGC container registry supports three different user roles:

  • Organization Administrator

    Capabilities:

    • Create teams
    • Add or remove uses to or from organizations
    • Add or remove users to or from teams
    • Push, pull, and run Docker images to and from all customer registry spaces
    • Pull and run Docker images from the NVIDIA public registry.
  • Team Administrator

    Capabilities:

    • Add or remove users to or from teams
    • Pull, push, and run Docker images to and from any organization or team spaces of which the user is a member
    • Pull and run Docker images from the NVIDIA public registry.
  • User

    Capabilities:

    • Pull, push, and run Docker images from any organization or team spaces of which the user is a member
    • Pull and run Docker images from the NVIDIA public registry

3. Setting Up and Activating Your NGC Account

3.1. Preparing the NGC Enterprise Account

At least one person from an enterprise must be assigned as the organization administrator for the NGC account. Make sure that the following information for your organization has been provided to NVIDIA Enterprise Support:

  • Organization name

    This name identifies the organization registry space that is available to all users in your organization.

  • Organization administrator name and email

    This is the person responsible for adding users and team spaces to the registry.

  • Authentication method for user accounts (IT-managed by SAML, or DGX account)

    IT-managed by SAML method integrates with your domain login as a single sign-on.

    NGC accounts are independent of your organization’s IT structure.

3.2. Signing Up for an NGC Account

Signing Up as the Initial Organization Administrator

Once NVIDIA has received the information described in Preparing the NGC Enterprise Account, the NVIDIA NGC team will set up the organization's space within the NGC container registry, set up the administrator account and authentication method, and then send a welcome email to the administrator to inform that the NGC container registry is available for use.

Signing Up as a User within the Organization

If you are part of the organization, your organization administrator will need to add you to the account. Once you are added, you will receive an invitation email and will be able to activate the account.

3.3. Activating Your NGC Account

After NVIDIA or your organization administrator sets up your account, you will receive a welcome email.

  1. Click the link in the email to launch the NGC sign-in screen in a browser.
  2. Enter your organization email, then click Sign In.
  3. Set up a password, depending on the authentication method set up by your organization.

    You may need to create a password or you may need to log in using your organization's single sign-on credentials.

  4. Click Accept at the NVIDIA GPU Cloud Terms of Use screen.
  5. At the Set Your Organization screen, select the organization that you want to set for this session, then click Sign In.

    This sets the organization or team registry space view for this login to the website.

    You can switch to other organization or team views of which you are a member once you are logged in.

3.4. Overview of the NGC Website

The NGC website opens to a screen similar to the following:

  • In the upper right corner is an icon representing you, the user, and the current registry space view .
  • The left side menu lists the functional pages that are available to you:

    Registry: Provides a list of all available repositories, their description, and instructions for pushing and pulling the container images.

    Teams: Shows the teams that are available to the user, and lets administrators add or remove users from specific teams. Organization administrators can also add (create) teams.

    Users: (Available only to administrators) Shows all active and invited members of the current team or organization view. Organization administrators an also add (invite) users.

    Configuration: Provides configuration functions

    These are explained more fully in the chapters Using the NGC Container Registry and Administrator Instructions.

4. Using the NGC Container Registry

Before using NGC container registry from the Docker command line, you need to log on to the NGC website and obtain your API Key. Your API Key authenticates you to use the registry.

The NGC website also provides useful information, such as:

  • The NGC container registry spaces that are available to you
  • The Docker repositories in each space
  • Guidance on Docker push and pull commands

4.1. Using the NGC Website

This section describes sections of the website that are of interest to users who will be accessing containers from the Docker command line.

4.1.1. Viewing the Repositories

The NGC website provides information about the repositories stored in each registry space.
  1. Log on to the NGC website. If you are a member of more than one organization, you will need to select which organization to be associated with for the session. The website opens to the Registry page.

    The Registry page shows a list of available registry spaces and the Docker repositories they contain, information about selected repositories, and pull/push commands for the selected repository. The Repositories section shows a list of all the available registry spaces.

  2. Click the name of any of the NGC container registry spaces to show or hide a list of Docker repositories that are stored in that space. This example shows the repositories contained within the nvidia registry space.

  3. Click one of the repositories to show a list of available tags for that Docker image as well as a readme that provides general information about the repository.
  4. To view the suggested push and pull commands for a specific image, select Pull or Push from the Registry-space/Repository section.

    Click the copy icon on the right side to copy the command to the clipboard.

    You can also copy the pull command for a specific tag by clicking the download icon in the tag list.

4.1.2. Getting Your NGC API Key

Your NGC API key authenticates your access to NGC container registry from the command line.

CAUTION:
Anyone with your API key can access all the services and resources to which you are entitled through your NGC account. Therefore, keep your API key secret and don't share it or store it where others can see or copy it.
  1. Use a web browser to log in to your NGC account on the NGC website.
  2. Click Get API Key either from
    • the upper right corner of the Registry page

    • or from the Configuration page

  3. In the API Key page that opens, click Generate API Key .

  4. In response to the warning that your old API key will become invalid, click Confirm.

    Your API key is displayed with examples of how to use it.

    You only need to generate an API Key once. NGC does not save your key, so store it in a secure place. If you misplace your API key, you can get a new API key from the NGC website whenever you need it. When you get your API key, a new key is generated, which invalidates any keys you may have obtained previously.

    Tip: You can copy your API key to the clipboard by clicking the Copy icon to the right of the API key.

4.2. Using NGC Container Registry from the Docker Command Line

4.2.1. Accessing the NGC Container Registry

You can access the NGC container registry by running a Docker command from your client computer. You are not limited to using your NVIDIA DGX platform to access the NGC container registry. You can use any Linux computer with Internet access on which Docker is installed.
Before accessing the NGC container registry, ensure that the following prerequisites are met:
  • Your NGC account is activated.
  • You have an NGC API key for authenticating your access to NGC container registry. For more information, see Getting Your NGC API Key.
  • You are logged in to your client computer as an administrator user.

    An alternate approach for enabling other users to run containers without giving them sudo privilege, and without having to type sudo before each docker command, is to add each user to the docker group, with the command:

    sudo usermod -aG docker $USER

    While this approach is more convenient and commonly used, it is less secure because any user who can send commands to the docker engine can escalate privilege and run root level operations. If you choose to use this method, only add users to the docker group who you would trust with root privileges.

  1. Log in to the NGC container registry.
    sudo docker login nvcr.io
  2. When prompted for your user name, enter the following text:
    $oauthtoken

    The $oauthtoken user name is a special user name that indicates that you will authenticate with an API key and not a user name and password.

  3. When prompted for your password, enter your NGC API key as shown in the following example.
    Username: $oauthtoken
    Password: my-api-key
    Tip: When you get your API key as explained in Getting Your NGC API Key, copy it to the clipboard so that you can paste the API key into the command shell when you are prompted for your password.

4.2.2. Uploading an NVIDIA Container Image onto Your System

No container images are preloaded onto a DGX system. Instead, containers are available for download from the NGC container registry. NVIDIA has provided a number of containers for download from the NGC container registry. If your organization has provided you with access to any custom containers, you can download those as well.

Before loading an NGC container image, ensure that the following prerequisites are met:
Tip: To browse the available containers in the NGC container registry, use a web browser to log in to your NGC account on the NGC website.
  1. Run the command to download the container that you want from the registry.
    sudo docker pull registry/registry-space/repository:tag
    registry
    The URL of the container registry, which for the NGC container registry is nvcr.io.
    registry-space
    The name of the space within the registry that contains the container. For example, nvidia is the registry space for containers provided by NVIDIA.
    repository
    Repositories are collections of containers of the same name, but distinguished from each other by their tags. Think of it as the main container name.
    tag
    A tag that identifies the version of the container.
  2. To confirm that the container was downloaded, list the Docker images on your system.
    sudo docker images

The following are several examples of pulling container images.

  • Example of pulling tensorflow:18.06-py3 from the nvidia registry space.

    ~$ sudo docker pull nvcr.io/nvidia/tensorflow:18.06-py3
    
  • Example of pulling a custom container image tagged v2.0 from the acme organization registry space.

    ~$ sudo docker pull nvcr.io/acme/custom-image:v2.0
  • Example of pulling a custom container image tagged v2.0 from the acme/team team registry space.

    ~$ sudo docker pull nvcr.io/acme/zoom/custom-image:v2.0

4.2.3. Tagging and Pushing a Container Image

You can upload custom images to the registry if you have write access to the registry space. Uploading a container image involves first tagging the image and then pushing the image to the registry space.

In the following examples, the user is a member of the Acme organization and the Zoom team within the Acme organization.

  • Tagging Example

    This example tags a local container image mycaffe in the acme/zoom team space with "v1.5".

    ~$ sudo docker tag mycaffe nvcr.io/acme/zoom/mycaffe:v1.5
  • Pushing Example

    This example pushes version v1.5 of the mycaffe local container image to the acme/zoom team space:

    ~$ sudo docker push nvcr.io/acme/zoom/mycaffe:v1.5

5. Administrator Instructions

This chapter explains the tasks that an organization or team administrator can perform from the NGC website.

5.1. Creating Teams

Creating teams is useful for allowing users to share images within a team while keeping them invisible to other teams in the same organization. Only organization administrators can create teams.

To create a team,

  1. Log on to the NGC website.
  2. Select Teams from the left side menu.
  3. From the Teams page, click Add Team.
  4. Enter a team name and description, then click Add Team.

5.2. Creating Users

As the organization administrator, you must create user accounts to allow others to use the NGC container registry within the organization.
  1. Log on to the NGC website.
  2. Click Users from the left side menu, then click Add New User.
    Note: It doesn’t matter which organization or team view is enabled; the new user is added only to the organization if they are assigned the User role. After adding the user, you can add them to individual teams as needed. If you assign the new user the Admin role, the user is added to all teams within the organization.
  3. Fill out the Add New User form for the new user as follows:
    1. Enter the display name and email where indicated.
    2. Click the Role Type list arrow and then select one of the user types.
      Note: If you select Admin, the user will be added to all teams within the organization.
  4. Click Add User when done.
An invitation email is automatically sent to the user.

5.3. Adding Users to Teams

Organization administrators can add users to any team in the organization. Team administrators can add users to their teams.
  1. Log on to the NGC website.
  2. Click Teams from the left side menu, then select the team that you want to add a user.
  3. In the Active Members section, click Add New User.
  4. In the Add User dialog, select one of the available users and then select a role.
Users can be members of more than one team. To add a user to another team, repeat these steps for any additional teams.

5.4. Changing User Roles

You can change user roles for any users you created.
  1. Log on to the NGC website.
  2. Select which registry space for which you want to change the user role.

    If one or more teams are set up, click the organization icon at the upper right corner and then select the organization space or one of the team spaces from the dropdown list.

  3. Click Users from the left side menu. A list of all the users in the current registry space appears.
  4. Select the user whose role you want to change. The User Information form appears.
  5. Click Edit User.
  6. Click the Role Type list arrow and then select the new user type.
  7. Click Save when done.

Getting Support for NVIDIA DGX Container Registry

For additional information on using the NVIDIA DGX Container Registry and for getting help if you encounter issues, send an email to enterprisesupport@nvidia.com with a description of your issue and a ticket will be created for you.

Notices

Notice

THE INFORMATION IN THIS GUIDE AND ALL OTHER INFORMATION CONTAINED IN NVIDIA DOCUMENTATION REFERENCED IN THIS GUIDE IS PROVIDED “AS IS.” NVIDIA MAKES NO WARRANTIES, EXPRESSED, IMPLIED, STATUTORY, OR OTHERWISE WITH RESPECT TO THE INFORMATION FOR THE PRODUCT, AND EXPRESSLY DISCLAIMS ALL IMPLIED WARRANTIES OF NONINFRINGEMENT, MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE. Notwithstanding any damages that customer might incur for any reason whatsoever, NVIDIA’s aggregate and cumulative liability towards customer for the product described in this guide shall be limited in accordance with the NVIDIA terms and conditions of sale for the product.

THE NVIDIA PRODUCT DESCRIBED IN THIS GUIDE IS NOT FAULT TOLERANT AND IS NOT DESIGNED, MANUFACTURED OR INTENDED FOR USE IN CONNECTION WITH THE DESIGN, CONSTRUCTION, MAINTENANCE, AND/OR OPERATION OF ANY SYSTEM WHERE THE USE OR A FAILURE OF SUCH SYSTEM COULD RESULT IN A SITUATION THAT THREATENS THE SAFETY OF HUMAN LIFE OR SEVERE PHYSICAL HARM OR PROPERTY DAMAGE (INCLUDING, FOR EXAMPLE, USE IN CONNECTION WITH ANY NUCLEAR, AVIONICS, LIFE SUPPORT OR OTHER LIFE CRITICAL APPLICATION). NVIDIA EXPRESSLY DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY OF FITNESS FOR SUCH HIGH RISK USES. NVIDIA SHALL NOT BE LIABLE TO CUSTOMER OR ANY THIRD PARTY, IN WHOLE OR IN PART, FOR ANY CLAIMS OR DAMAGES ARISING FROM SUCH HIGH RISK USES.

NVIDIA makes no representation or warranty that the product described in this guide will be suitable for any specified use without further testing or modification. Testing of all parameters of each product is not necessarily performed by NVIDIA. It is customer’s sole responsibility to ensure the product is suitable and fit for the application planned by customer and to do the necessary testing for the application in order to avoid a default of the application or the product. Weaknesses in customer’s product designs may affect the quality and reliability of the NVIDIA product and may result in additional or different conditions and/or requirements beyond those contained in this guide. NVIDIA does not accept any liability related to any default, damage, costs or problem which may be based on or attributable to: (i) the use of the NVIDIA product in any manner that is contrary to this guide, or (ii) customer product designs.

Other than the right for customer to use the information in this guide with the product, no other license, either expressed or implied, is hereby granted by NVIDIA under this guide. Reproduction of information in this guide is permissible only if reproduction is approved by NVIDIA in writing, is reproduced without alteration, and is accompanied by all associated conditions, limitations, and notices.

Trademarks

NVIDIA, the NVIDIA logo, DGX, DGX-1, and DGX Station are trademarks and/or registered trademarks of NVIDIA Corporation in the Unites States and other countries. Other company and product names may be trademarks of the respective companies with which they are associated.