Custom Certificate Support#

Overview of Custom Certificates#

You can use custom Certificate Authority (CA) certificates for host verification of services, registries, and package repositories.

This is automatically handled on a host-by-host basis in the following ways:

  • (automatic) Detecting and using the host’s certificate store

  • (automatic) Setting up Docker or Podman to trust certs in the certificate store

  • (optional) Adding certs to project containers at build and runtime

  • (optional) Configuring pip and other package managers

Automatic Detection#

Workbench automatically detects and uses the host certificate store.

The following standard locations are automatically added to the container runtime’s trusted certs.

  • Linux: /etc/ssl/certs

  • macOS: System Keychain

  • Windows: Windows Certificate Store

General Limitations#

  • Only the standard host certificate store will be added

  • Certificate store changes may require restarting the Workbench service and containers

  • Docker Desktop requires restarting both the Workbench service and Docker Desktop

  • Certificate errors are not handled separately but do appear in the Workbench service logs

  • Workbench doesn’t add certs to project containers by default, but you can set an option for this

Container Cert Configuration (optional)#

You must set a configuration option to add certificates to project containers.

  • You set a configuration option on a host-by-host, i.e. ___location-by-___location, basis

  • This is done with the service.project_custom_ca_enabled field in the config.yaml file

  • This will add the host certificate store to every project container built or run on that host

  • This adds all of the certificates in the store to the container

  • This will trigger rebuild notifications for all containers on the host when the store changes

Setting the Container Option#

The Desktop App lacks affordances to re-configure the Workbench service.

However, you can do this manually by editing a configuration file on the host.

  • You will edit the config.yaml file on the host

  • Depending on how Workbench was installed, that file is in the following ___location:

    • Linux: ~/.nvwb/config.yaml

    • macOS: $HOME/.nvwb/config.yaml

    • Windows (in the WSL distro NVIDIA-Workbench): home/workbench/.nvwb/config.yaml

  • Open config.yaml in a file editor and set the following field to true

    # Example config.yaml file
# This is a sample file. Your file may be different.
# The field may not be present in your file, so you may have to add it.

service:
  project_custom_ca_enabled: true

# This field enables custom CA certs in project containers.
# It adds the host certificate store to containers.
# Any changes to the store will trigger rebuilds.

  • Fully shutdown and restart Workbench on the host

FAQs#

What if I need to use a certificate or authority that is not in the host certificate store?#

Either you add it to the host certificate store, or you need to manually configure the container runtimes and the individual project containers you want to use it in.

Can I use certificates on a project-by-project basis instead of a host-by-host basis?#

No. If you want to do this, then you need to do it manually.

How do I add a certificate to the host certificate store?#

For help managing system certificates, contact your IT security team.