Sign images that MKE can trust

A key MKE feature prevents the deployment of untrusted images on the cluster, the use of which requires you to sign and push images to your MSR. To tie the signed images back to MKE, you must sign the images with the private keys of the MKE users. From an MKE client bundle, use key.pem as your private key, and cert.pem as your public key on an x509 certificate.

To sign images in a way that MKE can trust, you must:

1. Download a client bundle for the user account you want to use for signing the images.

2. Add the user’s private key to the trust store of your machine.

3. Initialize trust metadata for the repository.

4. Delegate signing for that repository to the MKE user.

5. Sign the image.

In the example scenario that follows, the nginx image is pulled from Docker Hub, tagged as msr.example.com/dev/nginx:1, pushed to MSR, and signed in a way that is trusted by MKE.

1. Download and extract an MKE client bundle into your local directory.

2. Load the private key into the local Docker trust store (~/.docker/trust):

   $ docker trust key load --name <user> key.pem
   

   Example output:

   Loading key from "key.pem"...
   Enter passphrase for new <user> key with ID a453196:
   Repeat passphrase for new <user> key with ID a453196:
   Successfully imported key from key.pem
   

3. Initiate trust metadata for an MSR repository.

   If you have not already done so, navigate to the MSR web UI and create a repository for your image. This example uses the nginx repository in the prod namespace.

   As part of initiating the repository, the public key of the MKE user must be added to the Notary server as a signer for the repository. You will be prompted for passphrases to protect the keys, and you should make a note of these passphrases.

   $ docker trust signer add --key cert.pem <user> msr.example.com/prod/nginx
   Adding signer "<user>" to msr.example.com/prod/nginx...
   Initializing signed repository for msr.example.com/prod/nginx...
   Enter passphrase for root key with ID 4a72d81:
   Enter passphrase for new repository key with ID e0d15a2:
   Repeat passphrase for new repository key with ID e0d15a2:
   Successfully initialized "msr.example.com/prod/nginx"
   Successfully added signer: <user> to msr.example.com/prod/nginx
   

4. Inspect the trust metadata of the repository to ensure that the user has been added.

   $ docker trust inspect --pretty msr.example.com/prod/nginx
   
   No signatures for msr.example.com/prod/nginx
   
   List of signers and their keys for msr.example.com/prod/nginx
   
   SIGNER              KEYS
   <user>                927f30366699
   
   Administrative keys for msr.example.com/prod/nginx
   
     Repository Key:       e0d15a24b7...540b4a2506b
     Root Key:             b74854cb27...a72fbdd7b9a
   

5. Sign the image tag. The following steps include downloading the image from Docker Hub, tagging the image for the user’s MSR repository, pushing the image to the user’s repository, and signing the tag with the user’s key.

   $ docker pull nginx:latest
   
   $ docker tag nginx:latest msr.example.com/prod/nginx:1
   
   $ docker trust sign msr.example.com/prod/nginx:1
   Signing and pushing trust data for local image msr.example.com/prod/nginx:1, may overwrite remote trust data
   The push refers to repository [msr.example.com/prod/nginx]
   6b5e2ed60418: Pushed
   92c15149e23b: Pushed
   0a07e81f5da3: Pushed
   1: digest: sha256:5b49c8e2c890fbb0a35f6050ed3c5109c5bb47b9e774264f4f3aa85bb69e2033 size: 948
   Signing and pushing trust metadata
   Enter passphrase for <user> key with ID 927f303:
   Successfully signed msr.example.com/prod/nginx:1
   

6. Inspect the trust metadata to ensure that the image tag has been signed.

   $ docker trust inspect --pretty msr.example.com/prod/nginx:1
   
   Signatures for msr.example.com/prod/nginx:1
   
   SIGNED TAG          DIGEST                   SIGNERS
   1                   5b49c8e2c8...90fbb2033   <user>
   
   List of signers and their keys for msr.example.com/prod/nginx:1
   
   SIGNER              KEYS
   <user>                927f30366699
   
   Administrative keys for msr.example.com/prod/nginx:1
   
     Repository Key:       e0d15a24b74...96540b4a2506b
     Root Key:             b74854cb27c...1ea72fbdd7b9a
   

   Alternatively, you can review the signed image from the MSR web UI.