-
Notifications
You must be signed in to change notification settings - Fork 84
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
doc: update spec for feature sign/verify local images #601
Conversation
Signed-off-by: Yi Zha <yizha1@microsoft.com>
Codecov Report
📣 This organization is not using Codecov’s GitHub App Integration. We recommend you install it so Codecov can continue to function properly for your repositories. Learn more @@ Coverage Diff @@
## main #601 +/- ##
==========================================
- Coverage 34.36% 33.63% -0.73%
==========================================
Files 32 32
Lines 1848 1888 +40
==========================================
Hits 635 635
- Misses 1192 1232 +40
Partials 21 21 see 4 files with indirect coverage changes 📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more |
Signed-off-by: Yi Zha <yizha1@microsoft.com>
Signed-off-by: Yi Zha <yizha1@microsoft.com>
Signed-off-by: Yi Zha <yizha1@microsoft.com>
should |
specs/commandline/list.md
Outdated
@@ -29,6 +29,7 @@ Aliases: | |||
Flags: | |||
-d, --debug debug mode | |||
-h, --help help for list | |||
--local-artifact [Preview] list signatures associated with the artifact in OCI layout directory |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- Can we considering inferring that its a file path? @priteshbandi also brought this up.
- Secondly if the flag is needed can we call it something like --file or --path etc. --local is quite subjective.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For the option, what if we considered something more flexible than just a boolean. If we use something like --type (maybe this isn't the best name, but I think the concept is interesting) we could specify through the option that it is a directory. That would allow us to easily incorporate new modes for tarballs, SBOMs, or other files that could be added in the future.
Example:
notation sign $IMAGE
notation sign --type dir /path/to/registry.acme-rockets.io/net-monitor:v2
notation sign --type tar hello-world.tar
...
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@shizhMSFT @patrickzheng200 @qweeah @priteshbandi @vaninrao10 @FeynmanZhou @toddysm @sajayantony please take a look at Kody's comment above. Now we have these options:
--local-content
--local-artifact
--path <file path | dir path>
--file
--use-oci-layout
--oci-dir
--offline
file://./
--dirpath
--target-path
--type <dir|tar|other types>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In fact, if @yizha1 could remember, the very first version of my design was pretty similar to Kody's suggestion, i.e. specifying type of the user input. So personally speaking, I think it's a good idea as long as there's no usability concern (users need to know what options are available in Notation, and what type their input belong to).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I vote for option 3: --path <file path | dir path>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Agree with adding --target type=...
flag in v1.0.0. There is only one target type oci-layout
in RC.4, it's reasonable to use --oci-layout
as a shorthand for --target type=oci-layout
.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I am not sure having shorthand is a good idea. Having too many switches pollutes the CLI and makes its use hard to use.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@toddysm We will consider adding --target type=
if the time allows for 1.0. For RC.4 it is a good start, since we only have one type now, compared to --target type=oci-layout
, --oci-layout
is short and convenient. Shorthand could be a good practice for some scenarios, if we have multiple choice, and we know what option 80% users will choose, then shorthand will be convenient for them, since it is short. In the meantime, we could also support 20% scenarios with the full flag. In our cases, OCI image layout could be the most choice, since it is the only standard now OCI images and other OCI artifacts can be stored in a directory structure under filesystem (could be completely offline), and easy to copy to remote registry.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
My problem is that the main scenario is not that one. People do not want to create the layout before signing. A good user experience will be to reference the docker image and do all the work behind the scenes. Also, another local signing scenario is just signing a blob, like file for example, which doesn't require OCI layout at all. The current experience to ask the user to expand the image in OCI layout is suboptimal. If this is the only option then yes - this will be > 80% of the cases but it is a very little percentage of what people really want to do.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As discussed, --oci-layout
and --scope
will be experimental feature which requires system variable NOTATION_EXPERIMENTAL
to be set.
|
specs/commandline/list.md
Outdated
@@ -29,6 +29,7 @@ Aliases: | |||
Flags: | |||
-d, --debug debug mode | |||
-h, --help help for list | |||
--local-artifact [Preview] list signatures associated with the artifact in OCI layout directory |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
--path
and other generic terms are ambiguous if we want to sign a single file in the future. For instance, --path a.tar
can mean that we are processing the a.tar
as it is or the content in the a.tar
.
In fact, I think --type <type>
makes more sense. cobra
also allows use to type --type=<type>
For examples,
--type=oci
or--type=dir
for OCI-Layout in a folder--type=oci
or--type=tar
for OCI-layout in a tarball--type=file
is reserved for future file signing--type=desc
is reserved for future descriptor signing
However, --type=<type>
is still not straightforward.
As a reference, oras introduces the following flag:
--target type=<type>[[,<key>=<value>][...]]
For better UX, the boolean flag
--oci-layout
is introduced as an alias of--target type=oci-layout
.
Similarly, we could also follow the practice of oras
.
notation sign registry.acme-rockets.io/net-monitor:v2 # remote registry
notation sign --oci-layout registry.acme-rockets.io/net-monitor:v2 # oci-layout folder
notation sign --oci-layout net-monitor.tar:v2 --output net-monitor_v2.sig # oci-layout tarball
notation sign --descriptor desc.json --output desc.sig # descriptor
notation sign --file file.bin --output file.sig # standalone file
notation list registry.acme-rockets.io/net-monitor:v2 # remote registry
notation list --oci-layout registry.acme-rockets.io/net-monitor:v2 # oci-layout folder
notation list --oci-layout net-monitor.tar:v2 # oci-layout tarball
notation verify registry.acme-rockets.io/net-monitor:v2 # remote registry
notation verify --scope registry.acme-rockets.io/net-monitor --oci-layout registry.acme-rockets.io/net-monitor:v2 # oci-layout folder
notation verify --scope registry.acme-rockets.io/net-monitor --oci-layout net-monitor.tar:v2 # oci-layout tarball
notation verify --scope registry.acme-rockets.io/net-monitor --descriptor desc.json --signature desc.sig # descriptor
notation verify --scope registry.acme-rockets.io/net-monitor --file file.bin --signature file.sig # standalone file
Signed-off-by: Yi Zha <yizha1@microsoft.com>
Signed-off-by: Yi Zha <yizha1@microsoft.com>
Signed-off-by: Yi Zha <yizha1@microsoft.com>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM
Signed-off-by: Yi Zha <yizha1@microsoft.com>
Signed-off-by: Yi Zha <yizha1@microsoft.com>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM
Signed-off-by: Yi Zha <yizha1@microsoft.com>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM
This PR adds local sign/list/verification for OCI image layout directory. For RC.4: 1. It only supports storing the generated signature into the target OCI layout directory. 2. It supports listing signatures within the OCI layout directory. 3. It only supports verifying signatures within the target OCI layout directory. This PR is based on spec PR: #601 (Merged). This PR is dependent on the corresponding notation-go PR: notaryproject/notation-go#288. Please review the notation-go PR first. Resolves #283. Both remote registry and oci-layout scenario are tested. E2E tests are also included. --------- Signed-off-by: Patrick Zheng <patrickzheng@microsoft.com>
Update specs for feature sign/verify local images
Signed-off-by: Yi Zha yizha1@microsoft.com