Document the experimental registry signature endpoint #3556

mfojtik · 2017-01-23T10:09:37Z

This is WIP, I would like to add example of how you can sign the image using atomic sign or atomic push (@aweiteka to the rescue :-)

@openshift/team-documentation @miminar @legionus PTAL

Also i'm not sure what is the "right" section where this documentation should live (do we have something like "advanced registry" chapter?

The relevant Origin PR: openshift/origin#12504

Also this documentation is for 3.4.1+ (do we have any label that says what is the target release? ;-)

aweiteka

Since this is a reference for someone integrating with the API it would be good to have a pointer to this page from the rest_api/index.adoc overview page. That would also tie in the story that these are useful OCP extensions found all in one place.
Consider swapping the order so writing comes before reading to make for an example that actually works.

aweiteka · 2017-01-23T13:21:48Z

install_config/registry/accessing_registry.adoc

the {product-title} API, but...

aweiteka · 2017-01-23T13:35:11Z

install_config/registry/accessing_registry.adoc

See https://docs.docker.com/registry/spec/api/[upstream API documentation] for general information about the docker registry API.

aweiteka · 2017-01-23T13:35:29Z

install_config/registry/accessing_registry.adoc

==== Reading Image Signatures

---- GET /extensions/v2/{namespace}/{name}/signatures/sha256:{digest} ----

aweiteka · 2017-01-23T13:35:49Z

install_config/registry/accessing_registry.adoc

==== Writing Image Signatures

---- PUT /extensions/v2/{namespace}/{name}/signatures/sha256:{digest} ----

mfojtik · 2017-01-24T10:45:31Z

@aweiteka thanks! comments addressed.

miminar

Just a few remarks.

miminar · 2017-01-24T13:21:04Z

install_config/registry/accessing_registry.adoc

API - can we use etcd, storage or database instead?

we can but we don't at this point? (don't want to make it more confusing)

Let me explain. When you say API, I imagine just an interface, not a storage. So I find it hard to imagine that API stores something.So I wonder if there's any better word we can use as a replacement for the API. Another attempt: key value store?

How about, "The image signatures are stored in the {product-title} key-value store via API"?

miminar · 2017-01-24T13:23:38Z

install_config/registry/accessing_registry.adoc

digest includes sha256: prefix

miminar · 2017-01-24T13:27:41Z

install_config/registry/accessing_registry.adoc

Explain that the first part is image name and the second is signature name. And that the first part must match the <digest> parameter of the endpoint.

s/character/characters

miminar · 2017-01-24T13:28:50Z

install_config/registry/accessing_registry.adoc

digest includes sha256:
https://github.com/docker/distribution/blob/master/docs/spec/api.md#content-digests

miminar · 2017-01-24T13:31:06Z

install_config/registry/accessing_registry.adoc

<image-name>@<signature-name> or something like that

ahardin-rh · 2017-02-07T18:12:03Z

install_config/registry/accessing_registry.adoc

link:https://docs.docker.com/registry/spec/api/[upstream API documentation]

ahardin-rh · 2017-02-07T18:13:29Z

install_config/registry/accessing_registry.adoc

Place this ID above the heading:
[[writing-image-signatures]]

ahardin-rh · 2017-02-07T18:14:40Z

install_config/registry/accessing_registry.adoc

s/Image/image,
s/needs to have/must have

ahardin-rh · 2017-02-07T18:16:34Z

install_config/registry/accessing_registry.adoc

the signed Docker image into the {product-title} ...

ahardin-rh · 2017-02-07T18:17:00Z

install_config/registry/accessing_registry.adoc

add this ID before the heading:
[[reading-image-signatures]]

ahardin-rh · 2017-02-07T18:17:38Z

install_config/registry/accessing_registry.adoc

s/Image/image (a few instances across the page)

tried to fix them all.. in some cases I was refering to image and in some cases to API Image object... I dunno if we make distincion between them.

miminar · 2017-03-07T10:40:02Z

install_config/registry/accessing_registry.adoc

The name field can be confused with the <name> from the curl command above. Maybe ` could be used instead there?

it says "name field"

miminar · 2017-03-07T11:12:53Z

install_config/registry/accessing_registry.adoc

The sentence makes sense to me until sent.

mfojtik · 2017-03-07T11:13:10Z

@ahardin-rh @miminar tried to address all comments, PTAL

miminar · 2017-03-07T11:18:15Z

install_config/registry/accessing_registry.adoc

+[[writing-image-signatures]]
+==== Writing Image Signatures
+In order to add a new signature to the Image, users can use the HTTP `PUT` method together
+with the JSON payload sent the extensions endpoint:


I understand this sentence until sent.

Still valid.

miminar · 2017-03-07T11:22:42Z

install_config/registry/accessing_registry.adoc

+
+====
+----
+$ curl -X PUT --data @signature.json http://<user>:<token>@<registry-endpoint>:5000/extensions/v2/<namespace>/<name>/signatures/sha256:<digest>


To be consistent, replace all the occurences of sha256:<digest> with just <digest>.

miminar

Just a few minor glitches.

This is provided by the OpenShift-integrated registry. This is equivalent to the atomic: transport (in the “openshift”) subpackage, but it requires less code and notably does not require an OpenShift login context to be configured. See openshift/origin#12504 and openshift/openshift-docs#3556 for more information on this API extension. Signed-off-by: Miloslav Trmač <mitr@redhat.com>

This is provided by the OpenShift-integrated registry. This is equivalent to the atomic: transport (in the “openshift”) subpackage, but it requires less code and notably does not require an OpenShift login context to be configured. See openshift/origin#12504 and openshift/openshift-docs#3556 for more information on this API extension. To preserve compatibility, we always check for a configured lookaside sigstore first; if that is set up, we use the lookaside and ignore the registry-native signature storage. Usually the user would not bother to set up the lookaside, and use the native mechanism. Signed-off-by: Miloslav Trmač <mitr@redhat.com>

This is provided by the OpenShift-integrated registry. This is equivalent to the atomic: transport (in the “openshift”) subpackage, but it requires less code and notably does not require an OpenShift login context to be configured. See openshift/origin#12504 and openshift/openshift-docs#3556 for more information on this API extension. To preserve compatibility, we always check for a configured lookaside sigstore first; if that is set up, we use the lookaside and ignore the registry-native signature storage. Usually the user would not bother to set up the lookaside, and use the native mechanism. The code is mostly trivial; the only non-obvious aspect is the loop in putSignaturesToAPIExtension, which is a pretty direct translation of openshiftImageDestination.PutSignatures. Signed-off-by: Miloslav Trmač <mitr@redhat.com>

adellape · 2017-06-08T21:16:07Z

Document: Add registry endpoint for reading and writing image signatures

adellape · 2017-06-20T20:49:50Z

Closing this and continuing via #4623, PTAL there.

This is provided by the OpenShift-integrated registry. This is equivalent to the atomic: transport (in the “openshift”) subpackage, but it requires less code and notably does not require an OpenShift login context to be configured. See openshift/origin#12504 and openshift/openshift-docs#3556 for more information on this API extension. To preserve compatibility, we always check for a configured lookaside sigstore first; if that is set up, we use the lookaside and ignore the registry-native signature storage. Usually the user would not bother to set up the lookaside, and use the native mechanism. The code is mostly trivial; the only non-obvious aspect is the loop in putSignaturesToAPIExtension, which is a pretty direct translation of openshiftImageDestination.PutSignatures. Signed-off-by: Miloslav Trmač <mitr@redhat.com>

aweiteka suggested changes Jan 23, 2017

View reviewed changes

mfojtik force-pushed the signature-endpoint branch from d37c23e to 13d3102 Compare January 24, 2017 10:45

miminar suggested changes Jan 24, 2017

View reviewed changes

ahardin-rh reviewed Feb 7, 2017

View reviewed changes

install_config/registry/accessing_registry.adoc Outdated

Copy link

Contributor

ahardin-rh Feb 7, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Place this ID above the heading:
[[writing-image-signatures]]

ahardin-rh reviewed Feb 7, 2017

View reviewed changes

install_config/registry/accessing_registry.adoc Outdated

Copy link

Contributor

ahardin-rh Feb 7, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/Image/image,
s/needs to have/must have

ahardin-rh reviewed Feb 7, 2017

View reviewed changes

install_config/registry/accessing_registry.adoc Outdated

Copy link

Contributor

ahardin-rh Feb 7, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the signed Docker image into the {product-title} ...

ahardin-rh reviewed Feb 7, 2017

View reviewed changes

install_config/registry/accessing_registry.adoc Outdated

Copy link

Contributor

ahardin-rh Feb 7, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

add this ID before the heading:
[[reading-image-signatures]]

ahardin-rh reviewed Feb 7, 2017

View reviewed changes

ahardin-rh added this to the Next Release milestone Feb 7, 2017

ahardin-rh added the branch/enterprise-3.4 label Feb 7, 2017

miminar reviewed Mar 7, 2017

View reviewed changes

Document the experimental registry signature endpoint

8804a2e

mfojtik force-pushed the signature-endpoint branch from 13d3102 to 8804a2e Compare March 7, 2017 11:12

miminar reviewed Mar 7, 2017

View reviewed changes

install_config/registry/accessing_registry.adoc Outdated

Copy link

miminar Mar 7, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The sentence makes sense to me until sent.

miminar reviewed Mar 7, 2017

View reviewed changes

miminar suggested changes Mar 7, 2017

View reviewed changes

mtrmac mentioned this pull request Mar 25, 2017

Add support for the X-Registry-Supports-Signatures API extension containers/image#255

Merged

bmcelvee modified the milestones: Next Release, Staging Apr 3, 2017

adellape self-assigned this Jun 8, 2017

adellape mentioned this pull request Jun 20, 2017

Document the experimental registry signature endpoint #4623

Merged

adellape closed this Jun 20, 2017

ahardin-rh removed this from the Next Release milestone Jun 27, 2017

ahardin-rh removed the branch/enterprise-3.4 label Jun 27, 2017

Document the experimental registry signature endpoint #3556

Document the experimental registry signature endpoint #3556

Uh oh!

Conversation

mfojtik commented Jan 23, 2017

Uh oh!

aweiteka left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mfojtik commented Jan 24, 2017

Uh oh!

miminar left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ahardin-rh Feb 7, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mfojtik commented Mar 7, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

miminar left a comment

Choose a reason for hiding this comment

Uh oh!

adellape commented Jun 8, 2017

ahardin-rh Feb 7, 2017 •

edited

Loading