crane/gcrane: add pages (#13853)

pages/common/crane-append.md

@@ -0,0 +1,33 @@
+# crane append
+
+> Push an image based on an (optional) base image.
+> Appends layers containing the contents of the provided tarballs.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane_append.md>.
+
+- Push image based on a base image:
+
+`crane append {{-b|--base}} {{image_name}}`
+
+- Push image with appended layer from tarball:
+
+`crane append {{-f|--new_layer}} {{layer_name1 layer_name2 ...}}`
+
+- Push image with appended layer with new tag:
+
+`crane append {{-t|--new_tag}} {{tag_name}}`
+
+- Push resulting image to new tarball:
+
+`crane append {{-o|--output}} {{path/to/tarball}}`
+
+- Use empty base image of type OCI media instead of Docker:
+
+`crane append --oci-empty-base`
+
+- Annotate resulting image as being based on the base image:
+
+`crane append --set-base-image-annotations`
+
+- Display help:
+
+`crane append {{-h|--help}}`

pages/common/crane-auth.md

@@ -0,0 +1,28 @@
+# crane auth
+
+> Log in or access credentials.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane_auth.md>.
+
+- Execute `crane auth` subcommand:
+
+`crane auth {{subcommand}}`
+
+- Implement credential helper:
+
+`crane auth get {{registry_address}} {{-h|--help}}`
+
+- Log in to a registry:
+
+`crane auth login {{registry_address}} {{-h|--help}} {{-p|--password}} {{password}} {{-password-stdin}} {{-u|--username}} {{username}}`
+
+- Log out of a registry:
+
+`crane auth logout {{registry_address}} {{-h|--help}}`
+
+- Retrieve a token for a remote repository:
+
+`crane auth token {{registry_address}} {{-H|--header}} {{-h|--help}} {{-m|--mount}} {{scope1 scope2 ...}} --push`
+
+- Display help:
+
+`crane auth {{-h|--help}}`

pages/common/crane-blob.md

@@ -0,0 +1,12 @@
+# crane blob
+
+> Read a blob from a registry.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane_blob.md>.
+
+- Read the blob from a registry:
+
+`crane blob {{blob_identifier}}`
+
+- Display help:
+
+`crane blob {{-h|--help}}`

pages/common/crane-catalog.md

@@ -0,0 +1,16 @@
+# crane catalog
+
+> List the repositories in a registry.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane_catalog.md>.
+
+- List the repositories in a registry:
+
+`crane catalog {{registry_address}}`
+
+- Print the full image reference:
+
+`crane catalog {{registry_address}} --full-ref`
+
+- Display help:
+
+`crane catalog {{-h|--help}}`

pages/common/crane-config.md

@@ -0,0 +1,12 @@
+# crane config
+
+> Get the configuration of an image.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane_config.md>.
+
+- Get the configuration of an image:
+
+`crane config {{image_name}}`
+
+- Display help:
+
+`crane config {{-h|--help}}`

pages/common/crane-copy.md

@@ -0,0 +1,24 @@
+# crane copy
+
+> Efficiently copy a remote image from source to target while retaining the digest value.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane_copy.md>.
+
+- Copy an image from source to target:
+
+`crane copy {{source}} {{target}}`
+
+- Copy all tags:
+
+`crane copy {{source}} {{target}} {{-a|--all-tags}}`
+
+- Set the maximum number of concurrent copies, defaults to GOMAXPROCS:
+
+`crane copy {{source}} {{target}} {{-j|--jobs}} {{int}}`
+
+- Avoid overwriting existing tags in target:
+
+`crane copy {{source}} {{target}} {{-n|--no-clobber}}`
+
+- Display help:
+
+`crane copy {{-h|--help}}`

pages/common/crane-delete.md

@@ -0,0 +1,12 @@
+# crane delete
+
+> Delete an image reference from its registry.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane_delete.md>.
+
+- Delete an image reference from its registry:
+
+`crane delete {{image_name}}`
+
+- Display help:
+
+`crane delete {{-h|--help}}`

pages/common/crane-digest.md

@@ -0,0 +1,20 @@
+# crane digest
+
+> Get the digest of an image.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane_digest.md>.
+
+- Get the digest of an image:
+
+`crane digest {{image_name}}`
+
+- Print the full image reference by digest:
+
+`crane digest {{image_name}} --full-ref`
+
+- Specify path to tarball containing the image:
+
+`crane digest {{image_name}} --tarball {{path/to/tarball}}`
+
+- Display help:
+
+`crane digest {{-h|--help}}`

pages/common/crane-export.md

@@ -0,0 +1,16 @@
+# crane export
+
+> Export filesystem of a container image as a tarball.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane_digest.md>.
+
+- Write tarball to stdout:
+
+`crane export {{image_name}} -`
+
+- Write tarball to file:
+
+`crane export {{image_name}} {{path/to/tarball}}`
+
+- Read image from stdin:
+
+`crane export - {{path/to/filename}}`

pages/common/crane-flatten.md

@@ -0,0 +1,17 @@
+# crane flatten
+
+> Flatten an image's layers into a single layer.
+> Pushes digest to original image repository if no tags are specified.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane_digest.md>.
+
+- Flatten an image:
+
+`crane flatten`
+
+- Apply new tag to flattened image:
+
+`crane flatten {{-t|--tag}} {{tag_name}}`
+
+- Display help:
+
+`crane flatten {{-h|--help}}`

pages/common/crane-index-append.md

@@ -0,0 +1,30 @@
+# crane index append
+
+> Append manifest to a remote index.
+> This sub-command pushes an index based on an (optional) base index, with appended manifests.
+> The platform for appended manifests is inferred from the config file or omitted if that is infeasible.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane_index_append.md>.
+
+- Append manifest to a remote index:
+
+`crane index append`
+
+- Reference to manifests to append to the base index:
+
+`crane index append {{-m|--manifest}} {{manifest_name1 manifest_name2 ...}}`
+
+- Tag to apply to resulting image:
+
+`crane index append {{-t|--tag}} {{tag_name}}`
+
+- Empty base index will have Docker media types instead of OCI:
+
+`crane index append --docker-empty-base`
+
+- Append each of its children rather than the index itself (defaults true):
+
+`crane index append --flatten`
+
+- Display help:
+
+`crane index append {{-h|--help}}`

pages/common/crane-index-filter.md

@@ -0,0 +1,20 @@
+# crane index filter
+
+> Modifies a remote index by filtering based on platform.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane_index_filter.md>.
+
+- Modify remote index:
+
+`crane index filter`
+
+- Specify the platform(s) to keep from base in the form os/arch{{/variant}}{{:osversion}}{{,<platform>}}:
+
+`crane index filter --platform {{platform1 platform2 ...}}`
+
+- Tag to apply to resulting image:
+
+`crane index filter {{-t|--tags}} {{tag_name}}`
+
+- Display help:
+
+`crane index filter {{-h|--help}}`

pages/common/crane-index.md

@@ -0,0 +1,17 @@
+# crane index
+
+> Modify an image index.
+> The subcommands `append` and `filter` have their own usage documentation.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane_index.md>.
+
+- Modify an image index:
+
+`crane index`
+
+- Modify an image index with subcommand:
+
+`crane index {{subcommand}}`
+
+- Display help:
+
+`crane index {{-h|--help}}`

pages/common/crane-ls.md

@@ -0,0 +1,20 @@
+# crane ls
+
+> List the tags in a repository.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane_ls.md>.
+
+- List the tags:
+
+`crane ls {{repository}}`
+
+- Print the full image reference:
+
+`crane ls {{repository}} --full-ref`
+
+- Omit digest tags:
+
+`crane ls {{-o|--omit-digest-tags}}`
+
+- Display help:
+
+`crane ls {{-h|--help}}`

pages/common/crane-manifest.md

@@ -0,0 +1,12 @@
+# crane manifest
+
+> Get the manifest of an image.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane_manifest.md>.
+
+- Get the manifest:
+
+`crane manifest {{image_name}}`
+
+- Display help:
+
+`crane manifest {{-h|--help}}`

pages/common/crane-mutate.md

@@ -0,0 +1,37 @@
+# crane mutate
+
+> Modify image labels and annotations.
+> The container must be pushed to a registry, and the manifest is updated there.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane_mutate.md>.
+
+- New annotations to set (default []):
+
+`crane mutate {{-a|--annotation}}/{{-l|--label}} {{annotation/label}}`
+
+- Path to tarball/command/entrypoint/environment variable/exposed-ports to append to image:
+
+`crane mutate {{--append}}/{{--cmd}}/{{--entrypoint}}/{{-e|--env}}/{{--exposed-ports}} {{var1 var2 ...}}`
+
+- Path to new tarball of resulting image:
+
+`crane mutate {{-o|--output}} {{path/to/tarball}}`
+
+- Repository in the form os/arch{{/variant}}{{:osversion}}{{,<platform>}} to push mutated image:
+
+`crane mutate --set-platform {{platform_name}}`
+
+- New tag reference to apply to mutated image:
+
+`crane mutate {{-t|--tag}} {{tag_name}}`
+
+- New user to set:
+
+`crane mutate {{-u|--user}} {{username}}`
+
+- New working dir to set:
+
+`crane mutate {{-w|--workdir}} {{path/to/workdir}}`
+
+- Display help:
+
+`crane mutate {{-h|--help}}`

pages/common/crane-pull.md

@@ -0,0 +1,24 @@
+# crane pull
+
+> Pull remote images by reference and store their contents locally.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane_pull.md>.
+
+- Pull remote image:
+
+`crane pull {{image_name}} {{path/to/tarball}}`
+
+- Preserve image reference used to pull as an annotation when used with --format=oci:
+
+`crane pull {{image_name}} {{path/to/tarball}} --annotate-ref`
+
+- Path to cache image layers:
+
+`crane pull {{image_name}} {{path/to/tarball}} {{-c|--cache_path}} {{path/to/cache}}`
+
+- Format in which to save images (default 'tarball'):
+
+`crane pull {{image_name}} {{path/to/tarball}} {{-format}} {{format_name}}`
+
+- Display help:
+
+`crane pull {{-h|--help}}`

pages/common/crane-push.md

@@ -0,0 +1,20 @@
+# crane push
+
+> Push local image contents to a remote registry.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane_push.md>.
+
+- Push local image to remote registry:
+
+`crane push {{path/to/tarball}} {{image_name}}`
+
+- Path to file with list of published image references:
+
+`crane push {{path/to/tarball}} {{image_name}} --image-refs {{path/to/filename}}`
+
+- Push a collection of images as a single index (required if path has multiple images):
+
+`crane push {{path/to/tarball}} {{image_name}} --index`
+
+- Display help:
+
+`crane push {{-h|--help}}`

pages/common/crane-rebase.md

@@ -0,0 +1,24 @@
+# crane rebase
+
+> Rebase an image onto a new base image.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane_rebase.md>.
+
+- Rebase image:
+
+`crane rebase`
+
+- New base image to insert:
+
+`crane rebase --new_base {{image_name}}`
+
+- Old base image to remove:
+
+`crane rebase --old_base {{image_name}}`
+
+- Tag to apply to rebased image:
+
+`crane rebase {{-t|--tag}} {{tag_name}}`
+
+- Display help:
+
+`crane rebase {{-h|--help}}`

pages/common/crane-registry.md

@@ -0,0 +1,25 @@
+# crane registry
+
+> This command serves a registry implementation on an automatically chosen port (:0), $PORT or --address.
+> The command blocks while the server accepts pushes and pulls and contents are can be stored in memory, and disk.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane_registry_serve.md>.
+
+- Serve a registry implementation:
+
+`crane registry serve`
+
+- Address to listen on:
+
+`crane registry serve --address {{address_name}}`
+
+- Path to a directory where blobs will be stored:
+
+`crane registry serve --disk {{path/to/store_dir}}`
+
+- Display help:
+
+`crane registry {{-h|--help}}`
+
+- Display help:
+
+`crane registry serve {{-h|--help}}`

pages/common/crane-tag.md

@@ -0,0 +1,13 @@
+# crane tag
+
+> Efficiently tag a remote image without downloading it, which differs from the `copy` command.
+> It skips the layer existence checks because we know the manifest already exists making it slightly faster.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane_tag.md>.
+
+- Tag remote image:
+
+`crane tag {{image_name}} {{tag_name}}`
+
+- Display help:
+
+`crane tag {{-h|--help}}`

pages/common/crane-validate.md

@@ -0,0 +1,24 @@
+# crane validate
+
+> Validate that an image is well-formed.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane_validate.md>.
+
+- Validate an image:
+
+`crane validate`
+
+- Skip downloading/digesting layers:
+
+`crane validate --fast`
+
+- Name of remote image to validate:
+
+`crane validate --remote {{image_name}}`
+
+- Path to tarball to validate:
+
+`crane validate --tarball {{path/to/tarball}}`
+
+- Display help:
+
+`crane validate {{-h|--help}}`

pages/common/crane-version.md

@@ -0,0 +1,13 @@
+# crane version
+
+> Print the version of a binary.
+> The version string is completely dependent on how the binary was built, so you should not depend on the version format. It may change without notice.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane_version.md>.
+
+- Display version:
+
+`crane version`
+
+- Display help:
+
+`crane version {{-h|--help}}`

pages/common/crane.md

@@ -0,0 +1,29 @@
+# crane
+
+> Container images managing tool.
+> Some subcommands such as `pull`, `push`, `copy`, etc. have their own usage documentation.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane.md/>.
+
+- Execute a `crane` subcommand:
+
+`crane {{subcommand}}`
+
+- Allow pushing non-distributable (foreign) layers:
+
+`crane --allow-nondistributable-artifacts {{subcommand}}`
+
+- Allow image references to be fetched without TLS:
+
+`crane --insecure {{subcommand}}`
+
+- Specify the platform in the form os/arch{{/variant}}{{:osversion}} (e.g. linux/amd64). (default all):
+
+`crane  --platform {{platform}} {{subcommand}}`
+
+- Enable debug logs for a subcommand:
+
+`crane {{-v|--verbose}} {{subcommand}}`
+
+- Display help for a subcommand:
+
+`crane {{-h|--help}} {{subcommand}}`

pages/common/gcrane-copy.md

@@ -0,0 +1,20 @@
+# gcrane copy
+
+> Efficiently copy a remote image from source to target while retaining the digest value.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/gcrane/README.md>.
+
+- Copy an image from source to target:
+
+`gcrane {{cp|copy}} {{source}} {{target}}`
+
+- Set the maximum number of concurrent copies, defaults to 20:
+
+`gcrane copy {{source}} {{target}} {{-j|--jobs}} {{nr_of_copies}}`
+
+- Whether to recurse through repositories:
+
+`grance copy {{source}} {{target}} {{-r|--recursive}}`
+
+- Display help:
+
+`gcrane copy {{-h|--help}}`

pages/common/gcrane-gc.md

@@ -0,0 +1,18 @@
+# gcrane gc
+
+> List images that are not tagged.
+> Will calculate images that can be garbage-collected.
+> This can be composed with `gcrane delete` to actually garbage collect them.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/gcrane/README.md>.
+
+- List untagged images:
+
+`gcrane gc {{repository}}`
+
+- Whether to recurse through repositories:
+
+`gcrane gc {{repository}} {{-r|--recursive}}`
+
+- Display help:
+
+`gcrane gc {{-h|--help}}`

pages/common/gcrane-help.md

@@ -0,0 +1,12 @@
+# gcrane help
+
+> Help provides help for any command in the application.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/gcrane/README.md>.
+
+- Display help for a subcommand:
+
+`gcrane help {{command}}`
+
+- Display help:
+
+`grance help {{-h|--help}}`

pages/common/gcrane-ls.md

@@ -0,0 +1,21 @@
+# gcrane ls
+
+> List the tags in a repository.
+> More complex form than `crane ls`, which allows for listing tags, manifest and sub-repositories.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/gcrane/README.md>.
+
+- List the tags:
+
+`gcrane ls {{repository}}`
+
+- Format response from the registry as JSON:
+
+`gcrane ls {{repository}} --json`
+
+- Whether to recurse through repositories:
+
+`gcrane ls {{repository}} {{-r|--recursive}}`
+
+- Display help:
+
+`gcrane ls {{-h|--help}}`

pages/common/gcrane.md

@@ -0,0 +1,31 @@
+# gcrane
+
+> Container images managing tool.
+> This tool implements a superset of the `crane` commands, with additional commands that are specific to `gcr.io`.
+> Some subcommands such as `append`, `auth`, `copy`, etc. have their own usage documentation which can be found under `crane`.
+> Some subcommands such as `completion`, `gc`, `help` are specific to gcrane and have their own usage documentation.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/gcrane/README.md>.
+
+- Execute a `gcrane` subcommand:
+
+`gcrane {{subcommand}}`
+
+- Allow pushing non-distributable (foreign) layers:
+
+`gcrane --allow-nondistributable-artifacts {{subcommand}}`
+
+- Allow image references to be fetched without TLS:
+
+`gcrane --insecure {{subcommand}}`
+
+- Specify the platform in the form os/arch{{/variant}}{{:osversion}} (e.g. linux/amd64). (default all):
+
+`gcrane --platform {{platform}} {{subcommand}}`
+
+- Enable debug logs:
+
+`gcrane {{-v|--verbose} {{subcommand}}`
+
+- Display help:
+
+`gcrane {{-h|--help}}`

pages/linux/gcrane-completion.md

@@ -0,0 +1,37 @@
+# gcrane completion
+
+> Generate the autocompletion script for gcrane for the specified shell.
+> The available shells are `bash`, `fish`, `powershell`, and `zsh`.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/gcrane/README.md>.
+
+- Generate the autocompletion script for your shell:
+
+`gcrane completion {{shell_name}}`
+
+- Disable completion descriptions:
+
+`grance completion {{shell_name}} --no-descriptions`
+
+- Load completions in your current shell session (bash/zsh):
+
+`source <(gcrane completion bash/zsh)>`
+
+- Load completions in your current shell session (fish):
+
+`gcrane completion fish | source`
+
+- Load completions for every new session (bash):
+
+`gcrane completion bash > /etc/bash_completion.d/gcrane`
+
+- Load completions for every new session (zsh):
+
+`gcrane completion zsh > "${fpath[1]}/_gcrane"`
+
+- Load completions for every new session (fish):
+
+`gcrane completion fish > ~/.config/fish/completions/gcrane.fish`
+
+- Display help:
+
+`gcrane completion {{shell_name}} {{-h|--help}}`

pages/osx/gcrane-completion.md

@@ -0,0 +1,37 @@
+# gcrane completion
+
+> Generate the autocompletion script for gcrane for the specified shell.
+> The available shells are `bash`, `fish`, `powershell`, and `zsh`.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/gcrane/README.md>.
+
+- Generate the autocompletion script for your shell:
+
+`gcrane completion {{shell_name}}`
+
+- Disable completion descriptions:
+
+`grance completion {{shell_name}} --no-descriptions`
+
+- Load completions in your current shell session (bash/zsh):
+
+`source <(gcrane completion bash/zsh)>`
+
+- Load completions in your current shell session (fish):
+
+`gcrane completion fish | source`
+
+- Load completions for every new session (bash):
+
+`gcrane completion bash > $(brew --prefix)/etc/bash_completion.d/gcrane`
+
+- Load completions for every new session (zsh):
+
+`gcrane completion zsh > $(brew --prefix)/share/zsh/site-functions/_gcrane`
+
+- Load completions for every new session (fish):
+
+`gcrane completion fish > ~/.config/fish/completions/gcrane.fish`
+
+- Display help:
+
+`gcrane completion {{shell_name}} {{-h|--help}}`

pages/windows/gcrane-completion.md

@@ -0,0 +1,25 @@
+# gcrane completion
+
+> Generate the autocompletion script for gcrane for the specified shell.
+> The available shells are `bash`, `fish`, `powershell`, and `zsh`.
+> More information: <https://github.com/google/go-containerregistry/blob/main/cmd/gcrane/README.md>.
+
+- Generate the autocompletion script for your shell:
+
+`gcrane completion {{shell_name}}`
+
+- Disable completion descriptions:
+
+`grance completion {{shell_name}} --no-descriptions`
+
+- Load completions in your current shell session (powershell):
+
+`gcrane completion powershell | Out-String | Invoke-Expression`
+
+- Load completions for every new session (powershell):
+
+`Add above command to powershell profile`
+
+- Display help:
+
+`gcrane completion {{shell_name}} {{-h|--help}}`