Document the experimental registry signature endpoint

[adellape]

Picks up #3556 and continues edits.

Preview:

http://file.rdu.redhat.com/~adellape/062117/signature-endpoint/dev_guide/image_signatures.html

[adellape]

Document: Add registry endpoint for reading and writing image signatures

[adellape]

@mfojtik @aweiteka This never got merged for 3.4, PTAL at my edits.

Also, should this content appear in the Developer Guide "Managing Images" topic instead?

https://docs.openshift.com/container-platform/3.5/dev_guide/managing_images.html

Feels like it would be too buried in the Install & Config guide, especially since it doesn't seem admin-specific.

FYI, I'm also going to be working on docs for https://trello.com/c/BIJBu7qi/788-5-images-fill-in-the-metadata-signature-fields-when-a-signature-is-valid so I'd probably put the content near each other.

Also, there was a comment in #3556 about wanting to show how to sign images using atomic sign or atomic push. I'd like to still do that, though I may ultimately link to either:

RHEL AH doc Managing Containers - Chapter 2. Signing Container Images

or KBase Article Container Image Signing Integration Guide to handle that. Thoughts/preferences?

[adellape]

The original had a comma at the end here and in the other JSON example, which I've removed.

[adellape]

I added "in the relevant project" here.

[adellape]

@openshift/team-documentation PTAL.

[ahardin-rh]

usually GPG-signed data ?

[ahardin-rh]

These examples provide a quick reference for making successful REST API calls. In these examples,

[ahardin-rh]

@adellape Just a few suggestions from me 🚀

[adellape]

@ahardin-rh Thanks! Updates made.

[adellape]

@mfojtik Ack the wording here?

[adellape]

@mfojtik @aweiteka I've now experimented (in a separate commit 359f774) w/ the idea of a new topic in the Dev Guide that just focuses on image signatures. Also adds sections on atomic push/sign and oc adm verify-image-signatures. Separate preview build here:

http://file.rdu.redhat.com/~adellape/062117/signature-endpoint/dev_guide/image_signatures.html

A lot of it placeholder, but WDYT in general?

[aweiteka]

Policy is a big gap in the doc, probably purposefully for this audience. We do need to address it: what the defaults are and where to go for changing config. NOTE: this is a big dev usability gap that we just have to deal with now.

[aweiteka]

The oc CLI can also be used

can be used (only supported way today)

[aweiteka]

There are two angles to signature verification:

• verify with CLI (covered here)
• signatures checked during image pull to the node (the missing policy discussion). We could just call this out at a high level here and punt until we get a better story.

[aweiteka]

Add: "The atomic CLI is available on Red Hat-based distributions, Red Hat Enterprise Linux, Centos and Fedora."

[aweiteka]

Given the less-than-ideal story, how about something like...

"OpenShift does not automate image signing. Signing requires a developer's private GPG key typically stored securely on a workstation. This document describes that workflow."

[aweiteka]

"content": "<base64_encoded_signature>"

"content": "<cryptographic_signature>"

[aweiteka]

"content": "<cryptographic_signature>"

[aweiteka]

I believe this is a cluster-scoped role, not project.

[adellape]

It looked to me like there was both (oc adm for cluster-scoped):

# oc policy add-role-to-user system:image-signer fred -n alexd-project
role "system:image-signer" added: "fred"

# oc adm policy add-cluster-role-to-user system:image-signer alexd
cluster role "system:image-signer" added: "alexd"

If this is accurate, I figured I would add info on the cluster-scoped role to:

https://docs.openshift.com/container-platform/3.5/install_config/registry/accessing_registry.html#access-user-prerequisites

^ Similar to the note in there about the system:image-builder role.

[aweiteka]

Based on my testing you can add a project-scoped image-signer role but it doesn't actually grant priv to write signatures. Must be granted at cluster level with

oc adm policy add-cluster-role-to-user system:image-signer alexd

[aweiteka]

See above.

[aweiteka]

Maybe clarify one would need this role when using the --save flag.

[aweiteka]

Turns out you need image-auditor with or without --save opt.

$ oc adm verify-image-signature sha256:cd29ad7799ac016c81ad3ba6a287dbb6d9aa7537ad5b091b8f11bc793025ce20 --expected-identity 172.30.1.1:5000/myproject/alpine --public-key /home/aweiteka/.gnupg/aweiteka-redhat.pub
Error from server (Forbidden): User "developer" cannot get images at the cluster scope

[aweiteka]

$GNUPGHOME/pubring.gpg, typically in path ~/.gnupg.

See openshift/origin#15080

[adellape]

Updates made per latest comments.

http://file.rdu.redhat.com/~adellape/062117/signature-endpoint/dev_guide/image_signatures.html

[adellape]

@aweiteka PTAL. And do you have a pointer on where to find more info for your comments in #4623 (comment) and #4623 (comment)?

[adellape]

Chatted offline, merging this as-is for now.

[adellape]

[rev_history]
|xref:../dev_guide/image_signatures.adoc#dev-guide-image-signatures[Image Signatures]
|New topic about signing and verifying container image signatures.
%

[adellape]

@bfallonf (tagging you since you're up for next week's release) I'm adding the dedicated and online labels to this PR even though it only actually shows up in 3.4 and 3.5 (ifdefs are in place), just to keep things in sync. Can you make sure the revhistory comment above is removed from the dedicated revhistory after the script but before publishing? Thx!

[vikram-redhat]

@adellape - you mentioned online and dedicated, but only asked the rev history removed from the dedicated one :). Looking at the PR, I think it needed to be removed from the online rev history as well, which I have done. If it should have been kept, let me know and I can do a follow up.

[adellape]

@vikram-redhat OK, I didn't mention Online since we don't publish revhistory for those books. Thanks tho.

[vikram-redhat]

@adellape - ugh. Of course. Sorry!