|
| 1 | +# Frequently Asked Questions |
| 2 | + |
| 3 | +Before diving into the [specification](spec.md), you should consider the following frequently asked questions |
| 4 | +and ideas about the overall design of your registry. |
| 5 | + |
| 6 | +**Q: How do I design my registry models for Blobs, Image Manifests, and Repositories?** |
| 7 | + |
| 8 | +By way of specifying the name of the repository (`<name>`) for upload endpoints, |
| 9 | +this gives you freedom to design your registry in several ways: |
| 10 | + |
| 11 | + - Having blobs linked 1:1 to a repository, and then referenced in Image Manifests only belonging to that repository (you wouldn't need to worry about blob sharing across repositories, and cleanup would be limited to ensuring the blob only isn't needed by the repository in question) |
| 12 | + - Having blobs linked to Image Manifests, which are linked to Repositories. |
| 13 | + - Having blobs not linked to any Image Manifest or Repository and shared amongst all blobs (and for this implementation idea you would need to ensure that blobs are not deleted that are still being used, and that there aren't any security loopholes with someone uploading a blob that would be used by another repository. |
| 14 | + |
| 15 | +If there is another design idea not listed, please contribute it to the specification. For all of the above designs, you should consider storage (organization), along with permissions and cleanup. Different registries with varying user groups will likely have different use cases that warrant different behavior. |
| 16 | + |
| 17 | +**Q: How do I handle garbage collection?** |
| 18 | + |
| 19 | +Based on the design you choose above, you might want to implement integrity checking. For example, when you upload a manifest all blobs that it references should already exist in your registry. |
| 20 | + |
| 21 | +**Q: How do I store the manifest?** |
| 22 | + |
| 23 | +It's typically easiest to store the manifest as the raw byte stream that was originally provided. If you want to do additional parsing of content (e.g. to derive layers or annotations) that can be done as well. |
| 24 | + |
| 25 | +**Q: What about annotations in manifests?** |
| 26 | + |
| 27 | +While the specification does not say anything about annotations, you might choose |
| 28 | +to parse a manifest and represent them in a model, for easy query. It's up to you |
| 29 | +how you want to design an Annotation table. For example, since annotations could contain |
| 30 | +secrets you might want to keep them within the scope of an image or repository. |
| 31 | + |
| 32 | +**Q: What kind of digest are we talking about?** |
| 33 | + |
| 34 | +For these push endpoints and generally all distribution specification mentions of blobs, we are generally refering to a sha256 digest, however [other types](https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests) could be supported. |
| 35 | + |
| 36 | +**Q: Can I change the upload location?** |
| 37 | + |
| 38 | +For a chunked upload, you could implement it so that each PATCH request uses the |
| 39 | +same `<location>`, but you could also generate new session ids for scoped uploads. |
| 40 | +This decision is up to you. Expiring and then generating a new `<location>` could better match specific chunks to upload sessions, but a single `<location>` shared across chunks could better support more parallel operations (if your registry can support this). |
| 41 | + |
| 42 | +**Q: Should I validate the content type of the patch request body?** |
| 43 | + |
| 44 | +The content type for blob uploads isn't meaningful since it's consistently the same (application/octet-stream). |
| 45 | +However, you may so choose to check that the content type is consistent for each chunk in the upload. |
| 46 | +It would not be logical for it to change part of the way through. |
| 47 | + |
| 48 | +**Q: Is there a suggested chunk size, or number of chunks?** |
| 49 | + |
| 50 | +There is currently no best practice for an upload size or number of chunks. |
| 51 | + |
| 52 | +**Q: What is the order of a push for some client?** |
| 53 | + |
| 54 | +Generally, the data dependency between components drives the order of operations. |
| 55 | +For example, you can't upload a mainfest without knowing the config blob and layer digests. You can't know the config blob digest without knowing the layer diffids. You can't know the layer digests until you've gzipped and uploaded them (unless you know them ahead of time). This generally means that we do an upload like: |
| 56 | + |
| 57 | + - blobs are uploaded first (config and layers) |
| 58 | + - blobs (optionally) are then linked to an image manifest (and the manifest uploaded) |
| 59 | + - the layers and manifest are linked to a repository |
| 60 | + |
| 61 | +Keep in mind that along with image layers, the config is a [separate blob](https://github.com/opencontainers/image-spec/blob/master/config.md#example) that describes the container runtime specification. |
| 62 | + |
| 63 | +**Q: Can the location session for a push expire?** |
| 64 | + |
| 65 | +While there is no detail in the specification about the session expiring, you could |
| 66 | +choose to expire it after, for example, a minute or an hour, in the case that you don't want an upload session to be re-used. If you choose to expire sessions, you should test this expiration time to ensure that it works for different kinds of network connectivity for your user base. |
| 67 | + |
| 68 | +**Q: What happens if the `<tagname>` (last) parameter does not exist?** |
| 69 | + |
| 70 | +There is no suggested behavior in the specification for what to do if the tag does not exist. Registries might consider ignoring te parameter, or assuming a non-existing tag is at the start or the end of the sorted list. In the first case, at the start of the list would imply returning the entire set of tags. In the second cast, at the end of the list would imply returningan empty list, as it references the last tag onward (an empty set). |
0 commit comments