Update docs/recipes for Singularity schema change

2019-11-06 23:09:47 +00:00 · 2019-11-06 23:09:47 +00:00 · 3e1b5ac930
--- a/docs/12-batch-shipyard-configuration-global.md
+++ b/docs/12-batch-shipyard-configuration-global.md
@ -31,17 +31,29 @@ global_resources:
  docker_images:
  - busybox
  singularity_images:
-    unsigned:
-    - shub://singularityhub/busybox
-    - shub://singularityhub/scientific-linux
-    - docker://busybox
+    - image: shub://singularityhub/busybox
+    - image: docker://busybox
+    - image: oras://myazurecr.azurecr.io/repo/myunsignedimage:1.0.0
+    - image: library://user/repo/image:1.0.0
+    - image: library://user/repo/encryptedimage:1.0.0
+      encryption:
+        certificate:
+          sha1_thumbprint: 123456789...
    signed:
    - image: library://sylabs/tests/signed:1.0.0
-      key_fingerprint: 8883491F4268F173C6E5DC49EDECE4F3F38D871E
-      key_file: /path/to/key/file
-    - image: oras://myazurecr.azurecr.io
-      key_fingerprint: 000123000123000123000123000123000123ABCD
-      key_file: /path/to/key/file
+      signing_key:
+        fingerprint: 8883491F4268F173C6E5DC49EDECE4F3F38D871E
+    - image: oras://myazurecr.azurecr.io/repo/mysignedimage:1.0.0
+      signing_key:
+        fingerprint: 000123000123000123000123000123000123ABCD
+        file: /path/to/key/file
+    - image: library://user/repo/encryptedimage:1.0.0
+      signing_key:
+        fingerprint: 000123000123000123000123000123000123ABCD
+        file: /path/to/key/file
+      encryption:
+        certificate:
+          sha1_thumbprint: 123456789...
  volumes:
    data_volumes:
      contdatavol:
@ -267,22 +279,46 @@ This property is required.
      increased latency to begin task execution if the image differs from a
      previous pull, and lead to potential inconsistencies between task
      executions. Note that `singularity_images` is incompatible with `native`
-      container support enabled pools.
+      container support enabled pools. For encrypted container support,
+      please see the [Singularity Encrypted Containers](https://sylabs.io/guides/3.4/user-guide/encryption.html)
+      documentation for more details.
      * (optional) `unsigned` is a list of Singularity images that will not be
        verified when installing on every compute node. `shub://`, `docker://`,
        `library://`, and `oras://` URI prefixes are supported.
+        * (required) `image` is the unsigned Singularity image.
+        * (optional) `encryption` is the image encryption properties. Only
+          images encrypted with an asymmetric RSA key pair are currently
+          supported in Batch Shipyard.
+            * (required) `certificate` is the PFX decryption certificate with
+              the appropriate private key that has been bound to the
+              Batch account. This cannot be a CER certificate as a private key
+              is required for image decryption.
+                * (required) `sha1_thumbprint` is the associated SHA-1
+                  thumbprint of the certificate. This must be associated with
+                  the PFX with the private key.
      * (optional) `signed` is a list of objects containing the Singularity
        image that will be verified when installing on every compute node as
        well as the information to verify the image. `library://`, and
        `oras://` URI prefixes are supported.
-        * (required) `image` is the Singularity image to verify.
-        * (required) `key_fingerprint` is the key fingerprint of the Singularity
-          image to verify. If no `key_file` is specified, it uses this key
-          fingerprint to pull the key from the default key server
-          "[https://keys.sylabs.io](https://keys.sylabs.io)"
-        * (optional) `key_file` is a local path to a public key file. The key
-          fingerprint of the key in `key_file` must match the
-          `key_fingerprint`.
+        * (required) `image` is the signed Singularity image.
+        * (required) `signing_key` is the signing key properties.
+            * (required) `fingerprint` is the key fingerprint of the
+              Singularity image to verify. If no `key_file` is specified, it
+              uses this key fingerprint to pull the key from the default key
+              server "[https://keys.sylabs.io](https://keys.sylabs.io)"
+            * (optional) `file` is a local path to a public key file. The key
+              fingerprint of the key in `file` must match the
+              `fingerprint`.
+        * (optional) `encryption` is the image encryption properties. Only
+          images encrypted with an asymmetric RSA key pair are currently
+          supported in Batch Shipyard.
+            * (required) `certificate` is the PFX decryption certificate with
+              the appropriate private key that has been bound to the
+              Batch account. This cannot be a CER certificate as a private key
+              is required for image decryption.
+                * (required) `sha1_thumbprint` is the associated SHA-1
+                  thumbprint of the certificate. This must be associated with
+                  the PFX with the private key.
    * (optional) `files` property specifies data that should be ingressed
      from a location accessible by the local machine (i.e., machine invoking
      `shipyard.py` to a shared file system location accessible by compute
--- a/docs/80-batch-shipyard-multi-instance-tasks.md
+++ b/docs/80-batch-shipyard-multi-instance-tasks.md
@ -34,7 +34,7 @@ Batch Shipyard, as of version `3.8.0`, provides seamless MPI launch
 integration for popular MPI runtimes, including OpenMPI, MPICH, MVAPICH,
 and Intel MPI. Users can now specify simply the runtime they wish to use
 and if the environment contains the proper runtime, the commandlines for
-launching will automatically be populated. In the case of RDMA VMs,
+launching will automatically be populated. In the case of SR-IOV IB/RDMA VMs,
 complexity of certain requirements such as exposing the IB PKEY are
 automatically handled.

@ -83,8 +83,8 @@ will attempt to initialize on the host with an MPI runtime that doesn't
 exist.

 ### Docker and MPI Mental Model
-With the basics reviewed above, we can construct a mental model of the layout
-of how a Dockerized MPI program will execute.
+Keeping the aforementioned basics in mind, we can construct a mental model
+of the layout of how a Dockerized MPI program will execute.

 The typical Docker package, distribute, deploy model usually ends up with an
 image being run with `docker run`. This is fine for a large majority of  use
@ -150,7 +150,7 @@ mounted in from the host OS, copied into the Docker image during build time
 via `COPY`, or generated during build time. Note that if you copy or generate
 the keys into your Docker image, publishing your Docker image will expose
 your private RSA key. Although external users will not be able to SSH into
-these running instances by default as this SSH port is not exposed externally,
+these running instances by default, as this SSH port is not exposed externally,
 it can still be a security risk if a compute node is compromised. If this is
 an unacceptable risk for your scenario, you should be mounting in a private
 key into the Docker image at runtime which is not published as part of the
--- a/recipes/HPCG-Infiniband-IntelMPI/README.md
+++ b/recipes/HPCG-Infiniband-IntelMPI/README.md
@ -37,8 +37,11 @@ included in the Linpack image.
 The global configuration should set the following properties:
 * `singularity_images` array must have a reference to a valid HPCG image
 that can be run with Intel MPI and Infiniband. This can be
-`library://alfpark/linpack/linpack:2018-intel-mkl` which is
+`image: library://alfpark/linpack/linpack:2018-intel-mkl` which is
 published on the [Singularity Library](https://cloud.sylabs.io/library/alfpark/linpack/linpack).
+Since this image is signed, it should be placed under the `signed` section
+with the appropriate `signing_key`. Please see the `config.yaml` file for
+more information.

 ### Jobs Configuration
 #### Docker-based
--- a/recipes/HPCG-Infiniband-IntelMPI/config/singularity/config.yaml
+++ b/recipes/HPCG-Infiniband-IntelMPI/config/singularity/config.yaml
@ -2,5 +2,7 @@ batch_shipyard:
  storage_account_settings: mystorageaccount
 global_resources:
  singularity_images:
-    unsigned:
-      - library://alfpark/linpack/linpack:2018-intel-mkl
+    signed:
+      - image: library://alfpark/linpack/linpack:2018-intel-mkl
+        signing_key:
+          fingerprint: B55AC090E5139130C112A5783C4D545F457737EB
--- a/recipes/HPLinpack-Infiniband-IntelMPI/README.md
+++ b/recipes/HPLinpack-Infiniband-IntelMPI/README.md
@ -38,6 +38,9 @@ The global configuration should set the following properties:
 that can be run with Intel MPI and Infiniband. This can be
 `library://alfpark/linpack/linpack:2018-intel-mkl` which is
 published on the [Singularity Library](https://cloud.sylabs.io/library/alfpark/linpack/linpack).
+Since this image is signed, it should be placed under the `signed` section
+with the appropriate `signing_key`. Please see the `config.yaml` file for
+more information.

 ### Jobs Configuration
 #### Docker-based
--- a/recipes/HPLinpack-Infiniband-IntelMPI/config/singularity/config.yaml
+++ b/recipes/HPLinpack-Infiniband-IntelMPI/config/singularity/config.yaml
@ -2,5 +2,7 @@ batch_shipyard:
  storage_account_settings: mystorageaccount
 global_resources:
  singularity_images:
-    unsigned:
-      - library://alfpark/linpack/linpack:2018-intel-mkl
+    signed:
+      - image: library://alfpark/linpack/linpack:2018-intel-mkl
+        signing_key:
+          fingerprint: B55AC090E5139130C112A5783C4D545F457737EB
--- a/recipes/OSUMicroBenchmarks-Infiniband-MVAPICH/README.md
+++ b/recipes/OSUMicroBenchmarks-Infiniband-MVAPICH/README.md
@ -28,6 +28,9 @@ The global configuration should set the following properties:
 * `singularity_images` array have a reference to a valid OSU
 Micro-Benchmark image with MVAPICH. This can be
 `library://alfpark/mvapich/mvapich:2.3.2`
+Since this image is signed, it should be placed under the `signed` section
+with the appropriate `signing_key`. Please see the `config.yaml` file for
+more information.

 ### Jobs Configuration
 The jobs configuration should set the following properties within the `tasks`
--- a/recipes/OSUMicroBenchmarks-Infiniband-MVAPICH/config/config.yaml
+++ b/recipes/OSUMicroBenchmarks-Infiniband-MVAPICH/config/config.yaml
@ -2,5 +2,7 @@ batch_shipyard:
  storage_account_settings: mystorageaccount
 global_resources:
  singularity_images:
-    unsigned:
-      - library://alfpark/mvapich/mvapich:2.3.2
+    signed:
+      - image: library://alfpark/mvapich/mvapich:2.3.2
+        signing_key:
+          fingerprint: B55AC090E5139130C112A5783C4D545F457737EB
--- a/recipes/OSUMicroBenchmarks-Infiniband-MVAPICH/config/pool.yaml
+++ b/recipes/OSUMicroBenchmarks-Infiniband-MVAPICH/config/pool.yaml
@ -12,3 +12,6 @@ pool_specification:
  inter_node_communication_enabled: true
  ssh:
    username: shipyard
+  container_runtimes:
+    install:
+      - singularity
--- a/recipes/TensorFlow-GPU/config/singularity/config.yaml
+++ b/recipes/TensorFlow-GPU/config/singularity/config.yaml
@ -3,4 +3,4 @@ batch_shipyard:
 global_resources:
  singularity_images:
    unsigned:
-    - docker://tensorflow/tensorflow:latest-gpu
+      - image: docker://tensorflow/tensorflow:latest-gpu
--- a/recipes/mpiBench-IntelMPI/config/singularity/config.yaml
+++ b/recipes/mpiBench-IntelMPI/config/singularity/config.yaml
@ -3,4 +3,4 @@ batch_shipyard:
 global_resources:
  singularity_images:
    unsigned:
-    - library://vincent.labonte/mpi/mpibench:intelmpi
+      - image: library://vincent.labonte/mpi/mpibench:intelmpi
--- a/recipes/mpiBench-MPICH/config/singularity/config.yaml
+++ b/recipes/mpiBench-MPICH/config/singularity/config.yaml
@ -3,4 +3,4 @@ batch_shipyard:
 global_resources:
  singularity_images:
    unsigned:
-    - library://vincent.labonte/mpi/mpibench:mpich
+      - image: library://vincent.labonte/mpi/mpibench:mpich
--- a/recipes/mpiBench-OpenMPI/config/singularity/config.yaml
+++ b/recipes/mpiBench-OpenMPI/config/singularity/config.yaml
@ -3,4 +3,4 @@ batch_shipyard:
 global_resources:
  singularity_images:
    unsigned:
-    - library://vincent.labonte/mpi/mpibench:openmpi
+      - image: library://vincent.labonte/mpi/mpibench:openmpi