{"id":24995341,"url":"https://github.com/launchplatform/oci-hooks-archive-overlay","last_synced_at":"2025-04-22T11:45:19.266Z","repository":{"id":176012328,"uuid":"654836899","full_name":"LaunchPlatform/oci-hooks-archive-overlay","owner":"LaunchPlatform","description":"An OCI hook for archiving overlay mount upperdir after container is done","archived":false,"fork":false,"pushed_at":"2023-07-02T23:23:50.000Z","size":129,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-04T15:47:27.651Z","etag":null,"topics":["containers","oci-hook"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LaunchPlatform.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-17T05:05:43.000Z","updated_at":"2025-02-02T02:26:19.000Z","dependencies_parsed_at":null,"dependency_job_id":"f841a9d1-a1c7-4bd3-862e-89c12a723da5","html_url":"https://github.com/LaunchPlatform/oci-hooks-archive-overlay","commit_stats":null,"previous_names":["launchplatform/oci-hooks-archive-overlay"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LaunchPlatform%2Foci-hooks-archive-overlay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LaunchPlatform%2Foci-hooks-archive-overlay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LaunchPlatform%2Foci-hooks-archive-overlay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LaunchPlatform%2Foci-hooks-archive-overlay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LaunchPlatform","download_url":"https://codeload.github.com/LaunchPlatform/oci-hooks-archive-overlay/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246200300,"owners_count":20739563,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["containers","oci-hook"],"created_at":"2025-02-04T15:35:17.944Z","updated_at":"2025-03-29T14:43:53.128Z","avatar_url":"https://github.com/LaunchPlatform.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# oci-hooks-archive-overlay\nAn OCI hook for archiving overlay mount upperdir after container is done\n\n# Why\n\nFor some OCI tools like [podman](https://podman.io), it allows you to mount a container image in either readonly or read-write mode.\nLike this:\n\n```bash\npodman run --mount type=image,source=my-data-image,destination=/data,rw=true -it alpine\n```\n\nA read-write mount in the OCI spec config may look like this\n\n```json\n{\n  \"destination\": \"/data\",\n  \"type\": \"overlay\",\n  \"source\": \"/home/user/.local/share/containers/storage/overlay-containers/f6e6a7a7eaeb695bb433da1e057d92d9c2e376fb9920792c809d2c1af49e5709/userdata/overlay/3190055391/merge\",\n  \"options\": [\n    \"lowerdir=/home/user/.local/share/containers/storage/overlay/7877ad4aca46f49c306c8044f0d2a1528b642db9aed165f8b022f2b59fc9c237/merged\",\n    \"upperdir=/home/user/.local/share/containers/storage/overlay-containers/f6e6a7a7eaeb695bb433da1e057d92d9c2e376fb9920792c809d2c1af49e5709/userdata/overlay/3190055391/upper\",\n    \"workdir=/home/user/.local/share/containers/storage/overlay-containers/f6e6a7a7eaeb695bb433da1e057d92d9c2e376fb9920792c809d2c1af49e5709/userdata/overlay/3190055391/work\",\n    \"private\",\n    \"userxattr\"\n  ]\n}\n```\n\nAs you can see it's an [overlayfs](https://docs.kernel.org/filesystems/overlayfs.html) mount.\nThen you can modify the content files of the image at the mounted directory in the container.\nFor many usecases, one could be to capture the changes made to the mounted from the container.\nGiven the example shown above, the changes made to the `merge` will result in the `upper` directory:\n\n```\n/home/user/.local/share/containers/storage/overlay-containers/f6e6a7a7eaeb695bb433da1e057d92d9c2e376fb9920792c809d2c1af49e5709/userdata/overlay/3190055391/upper\n```\n\nWith the changes to the files in the original mounted image captured, you can then make a layer-based file system with revision history.\nYou can think about using it like Docker images or OCI container images but with just data changes in each layers.\nThe job of this hook is to archive the `upperdir` after the container stops.\n\n# How\n\nTo use this hook, you need to add annotations to your container to tell it which upperdir of the desired overlay mount point and a given destination path to copy to after the container stops.\nThere are two types of annotation you can add, one for the mount point and another for the destination of archive.\n\n- com.launchplatform.oci-hooks.archive-overlay.**\u003cARCHIVE_NAME\u003e**.mount-point\n- com.launchplatform.oci-hooks.archive-overlay.**\u003cARCHIVE_NAME\u003e**.archive-to\n- com.launchplatform.oci-hooks.archive-overlay.**\u003cARCHIVE_NAME\u003e**.success (optional)\n- com.launchplatform.oci-hooks.archive-overlay.**\u003cARCHIVE_NAME\u003e**.method (optional)\n- com.launchplatform.oci-hooks.archive-overlay.**\u003cARCHIVE_NAME\u003e**.tar-content-owner (optional)\n\nThe `ARCHIVE_NAME` can be any valid annotation string without a dot in it.\nThe `mount-point` and `archive-to` annotations with the same archive name need to appear in pairs, otherwise it will be ignored.\nFor example, to archive the upperdir of mount point at `/data` to `/path/to/my-archive`, you can add annotations like this\n\n- `com.launchplatform.oci-hooks.archive-overlay.data.mount-point=/data`\n- `com.launchplatform.oci-hooks.archive-overlay.data.archive-to=/path/to/my-archive`\n\nPlease note that the `mount-point` path should be a `destination` field of the mount, i.e, it's in the container namespace.\nAnd the `archive-to` should be a valid path in the runtime namespace.\n\nHere's an example command with podman:\n\n```bash\npodman run \\\n    --annotation=com.launchplatform.oci-hooks.archive-overlay.data.mount-point=/data \\\n    --annotation=com.launchplatform.oci-hooks.archive-overlay.data.archive-to=/tmp/my-archive \\\n    --mount type=image,source=my-data-image,destination=/data,rw=true \\\n    -it alpine\n# Change /data folder in the container then exit\nls /tmp/my-archive\n```\n\nThe `success` is a path to the empty file to be created as an indicator of a successful archive.\nThe `method` option by default is `copy`, if you want to archive the upperdir as a tar.gz file, you can set it to `tar.gz` instead.\nIf you want to change the content file owner of the tar file, you can set `tar-content-owner` value, such as `2000` or `2000:3000`.\nPlease note that only integer uid and gid supported, username won't work.\n\n## Add poststop hook directly in the OCI spec\n\nThere are different ways of running a container, if you are generating OCI spec yourself and running OCI runtimes such as [crun](https://github.com/containers/crun) yourself, you can add the `poststop` hook directly into the spec file like this:\n\n```json\n{\n  \"//\": \"... other OCI spec content ...\",\n  \"hooks\": {\n    \"poststop\": [\n      {\n        \"path\": \"/usr/bin/archive_overlay\"\n      }\n    ]\n  }\n}\n```\n\nFor more information about the OCI spec schema, please see the [document here](https://github.com/opencontainers/runtime-spec/blob/48415de180cf7d5168ca53a5aa27b6fcec8e4d81/config.md#posix-platform-hooks).\n\n## Add OCI hook config\n\nAnother way to add the OCI hook is to create a OCI hook config file.\nHere's an example:\n\n```json\n{\n  \"version\": \"1.0.0\",\n  \"hook\": {\n    \"path\": \"/usr/bin/archive_overlay\"\n  },\n  \"when\": {\n    \"annotations\": {\n        \"com\\\\.launchplatform\\\\.oci-hooks\\\\.archive-overlay\\\\.([^.]+)\\\\.mount-point\": \"(.+)\",\n        \"com\\\\.launchplatform\\\\.oci-hooks\\\\.archive-overlay\\\\.([^.]+)\\\\.archive-to\": \"(.+)\"\n    }\n  },\n  \"stages\": [\"poststop\"]\n}\n```\n\nFor more information about the OCI hooks schema, please see the [document here](https://github.com/containers/podman/blob/v3.4.7/pkg/hooks/docs/oci-hooks.5.md).\n\n# Debug\n\nTo debug the hook, you can add `--log-level=debug` (or `trace` if you need more details) argument for the `archive_overlay` executable, it will print debug information.\nWith OCI runtimes like [crun](https://github.com/containers/crun), you can also add an annotation like this:\n\n```\nrun.oci.hooks.stderr=/path/to/stderr\n```\n\nto make the runtime redirect the stderr from the hook executable to specific file.\nPlease note that podman invokes poststop hook instead of delegating it to crun, so the annotation won't work for podman.\n\n## Syslog\n\nYou can also pass `--syslog` option to make the hook omits log messages to syslog.\nHowever, please ensure that you have syslog daemon running on your system otherwise the hook still runs but no log messages will be sent.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaunchplatform%2Foci-hooks-archive-overlay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flaunchplatform%2Foci-hooks-archive-overlay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaunchplatform%2Foci-hooks-archive-overlay/lists"}