| Name | pants-backend-oci JSON |
| Version |
0.6.1
JSON |
| download |
| home_page | None |
| Summary | An OCI plugin for the Pants build system |
| upload_time | 2024-03-28 21:14:43 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | None |
| license | MIT License Copyright (c) 2022 Tom Solberg Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
pantsbuild
pants
docker
oci
container
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# OCI backend for Pants
> **Warning**
> This plugin is in development. No stability is guaranteed! Contributions welcome.
This is a backend implementing support for building OCI images in pants; running them, and publishing them to container registries. To do this, this plugin uses three different tools:
* [umoci](https://github.com/opencontainers/umoci) for manipulating OCI images
* [runc](https://github.com/opencontainers/runc) for exeuction
* [skopeo](https://github.com/containers/skopeo) for pulling and pushing images
# Planned and missing features
* Currently there's no support for pulling tags, as that would break determinism
* Multi-platform SHA/.sig is untested/unsupported
* skopeo doesn't support MacOS, preventing pulling and pushing images.
* No "in-container" build steps
## Targets
There's six targets currently implemented, of which five are generic:
* `oci_pull_image`
* `oci_pull_images`
* `oci_image_build`
* `oci_image_empty`
* `oci_build_layer`
And one with some special language semantics:
* `oci_python_image` - this is the same as `oci_image_build`, but will prefer to set the entrypoint to `.pex` files.
### `oci_pull_image`
Pull an image from a repository with a specific digest.
``` python
oci_pull_image(
name="base-python",
repository="docker.io/library/python",
sha="b78b777208be08edd8f297035cdfbacddb45170ad778fd643c792ee045187e39"
)
```
| Argument | Meaning | Default value |
|---------------|--------------------------------------------------|-------------------------------------------------------|
| `name` | The target name | Same as any other target, which is the directory name |
| `repository` | Fully qualified repository name | **Required** |
| `sha` | The digest of the image, minus the @sha: prefix. | **Required** |
| `anonymous` | Whether to pull the image anonymously. | `false` |
| `decsription` | A description of the target | |
| `tags` | List of tags | `[]` |
### `oci_pull_images`
Pull multiple shas for an image, generating a target for each. In the below example, we'd get the targets `:python#slim` and `:python#buster`.
``` python
oci_pull_image(
name="python",
repository="docker.io/library/python",
variants={
"slim": "f8fbb2370c6314c806b2ddbec8d94375987e16bc122379bef979c6fc5e962920",
"buster": "97c123c899c8c9ca46248f4002ec4173322e0a1086b386efefac163c64967ba2"
}
)
```
| Argument | Meaning | Default value |
|---------------|----------------------------------------------|-------------------------------------------------------|
| `name` | The target name | Same as any other target, which is the directory name |
| `repository` | Fully qualified repository name | **Required** |
| `variants` | Dictionary with local tags to the remote sha | **Required** |
| `anonymous` | Whether to pull the image anonymously | `false` |
| `decsription` | A description of the target | |
| `tags` | List of tags | `[]` |
### `oci_build_image`
Build an image with the provided packages embedded.
``` python
oci_image_build(
name="my-server",
base=":python#slim",
repository="my-registry.example.com/a-namespace/an-image",
tag="latest",
packages=[":my_pex"]
)
```
| Argument | Meaning | Default value |
|---------------|--------------------------------------------------------------------------------|-------------------------------------------------------|
| `name` | The target name | Same as any other target, which is the directory name |
| `base` | The base image to use. Matches the `FROM` directive in a Dockerfile | **Required** |
| `packages` | Packaged targets to include. The first element will be used as the entrypoint. | `[]` |
| `repository` | Fully qualified repository name | Required when publishing |
| `tag` | Remote tag to use | Required when publishing |
| `decsription` | A description of the target | |
| `tags` | List of tags | `[]` |
### `oci_python_image`
Build a Python image with the provided packages embedded.
``` python
oci_python_image(
name="my-server",
base=":python#slim",
repository="my-registry.example.com/a-namespace/an-image",
main="/app/server/start.py",
tag="latest",
packages=[":my_pex"]
)
```
| Argument | Meaning | Default value |
|---------------|--------------------------------------------------------------------------------|-------------------------------------------------------|
| `name` | The target name | Same as any other target, which is the directory name |
| `base` | The base image to use. Matches the `FROM` directive in a Dockerfile | **Required** |
| `packages` | Packaged targets to include. The first element will be used as the entrypoint. | `[]` |
| `python_main` | The main file to run | The last `.pex` in the dependency list |
| `repository` | Fully qualified repository name | Required when publishing |
| `tag` | Remote tag to use | Required when publishing |
| `decsription` | A description of the target | |
| `tags` | List of tags | `[]` |
### `oci_image_empty`
An empty base image with no contents at all. This is declared as `//:empty` automatically, but you can use this to create new targets.
``` python
oci_image_empty(
name="empty",
)
```
| Argument | Meaning | Default value |
|---------------|--------------------------------------------------------------------------------|-------------------------------------------------------|
| `name` | The target name | Same as any other target, which is the directory name |
| `decsription` | A description of the target | |
| `tags` | List of tags | `[]` |
### `oci_build_layer`
Run an image command, and capture the configured output into a layer artifact, that can be injected into other images. This matches the `COPY --from` workflows.
oci_build_layer(
name="layer"
base=[":rust-1-70"],
packages=[":files"],
env=['RUSTC_OPTS=...'],
command=['cd /my-package && cargo build --release'],
outputs=['/my-package/target/release/my-package'],
)
```
| Argument | Meaning | Default value |
|---------------|--------------------------------------------------------------------------------|--------------------------------------------------------|
| `name` | The target name | Same as any other target, which is the directory name |
| `packages` | Packaged targets to include. The first element will be used as the entrypoint. | `[]` |
| `env` | Environment variables to set. Does not support interpolation. | `[]` |
| `outputs` | Paths to capture into the built layer. | `[]` |
| `exclude` | Globs to not include in the output. | `[]` |
| `decsription` | A description of the target | |
| `output_path` | The output path during `pants package` | A variant generated from the target name and directory |
| `tags` | List of tags | `[]` |
Raw data
{
"_id": null,
"home_page": null,
"name": "pants-backend-oci",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "pantsbuild pants docker oci container",
"author": null,
"author_email": "Tom Solberg <me@sbg.dev>",
"download_url": "https://files.pythonhosted.org/packages/e0/1c/5d7fdb3a2130bf3abfc0307253c79065bacd2465703e34626a5003ee905b/pants_backend_oci-0.6.1.tar.gz",
"platform": null,
"description": "# OCI backend for Pants\n\n\n\n> **Warning**\n> This plugin is in development. No stability is guaranteed! Contributions welcome.\n\nThis is a backend implementing support for building OCI images in pants; running them, and publishing them to container registries. To do this, this plugin uses three different tools:\n\n* [umoci](https://github.com/opencontainers/umoci) for manipulating OCI images\n* [runc](https://github.com/opencontainers/runc) for exeuction\n* [skopeo](https://github.com/containers/skopeo) for pulling and pushing images\n\n# Planned and missing features\n\n* Currently there's no support for pulling tags, as that would break determinism\n* Multi-platform SHA/.sig is untested/unsupported\n* skopeo doesn't support MacOS, preventing pulling and pushing images.\n* No \"in-container\" build steps\n\n## Targets\n\nThere's six targets currently implemented, of which five are generic:\n\n* `oci_pull_image`\n* `oci_pull_images`\n* `oci_image_build`\n* `oci_image_empty`\n* `oci_build_layer`\n\nAnd one with some special language semantics:\n\n* `oci_python_image` - this is the same as `oci_image_build`, but will prefer to set the entrypoint to `.pex` files.\n\n### `oci_pull_image`\n\nPull an image from a repository with a specific digest.\n\n``` python\noci_pull_image(\n name=\"base-python\",\n repository=\"docker.io/library/python\",\n sha=\"b78b777208be08edd8f297035cdfbacddb45170ad778fd643c792ee045187e39\"\n)\n```\n\n| Argument | Meaning | Default value |\n|---------------|--------------------------------------------------|-------------------------------------------------------|\n| `name` | The target name | Same as any other target, which is the directory name |\n| `repository` | Fully qualified repository name | **Required** |\n| `sha` | The digest of the image, minus the @sha: prefix. | **Required** |\n| `anonymous` | Whether to pull the image anonymously. | `false` |\n| `decsription` | A description of the target | |\n| `tags` | List of tags | `[]` |\n\n### `oci_pull_images`\n\nPull multiple shas for an image, generating a target for each. In the below example, we'd get the targets `:python#slim` and `:python#buster`.\n\n``` python\noci_pull_image(\n name=\"python\",\n repository=\"docker.io/library/python\",\n variants={\n \"slim\": \"f8fbb2370c6314c806b2ddbec8d94375987e16bc122379bef979c6fc5e962920\",\n \"buster\": \"97c123c899c8c9ca46248f4002ec4173322e0a1086b386efefac163c64967ba2\"\n }\n)\n```\n\n| Argument | Meaning | Default value |\n|---------------|----------------------------------------------|-------------------------------------------------------|\n| `name` | The target name | Same as any other target, which is the directory name |\n| `repository` | Fully qualified repository name | **Required** |\n| `variants` | Dictionary with local tags to the remote sha | **Required** |\n| `anonymous` | Whether to pull the image anonymously | `false` |\n| `decsription` | A description of the target | |\n| `tags` | List of tags | `[]` |\n\n### `oci_build_image`\n\nBuild an image with the provided packages embedded.\n\n``` python\noci_image_build(\n name=\"my-server\",\n base=\":python#slim\",\n repository=\"my-registry.example.com/a-namespace/an-image\",\n tag=\"latest\",\n packages=[\":my_pex\"]\n)\n```\n\n| Argument | Meaning | Default value |\n|---------------|--------------------------------------------------------------------------------|-------------------------------------------------------|\n| `name` | The target name | Same as any other target, which is the directory name |\n| `base` | The base image to use. Matches the `FROM` directive in a Dockerfile | **Required** |\n| `packages` | Packaged targets to include. The first element will be used as the entrypoint. | `[]` |\n| `repository` | Fully qualified repository name | Required when publishing |\n| `tag` | Remote tag to use | Required when publishing |\n| `decsription` | A description of the target | |\n| `tags` | List of tags | `[]` |\n\n### `oci_python_image`\n\nBuild a Python image with the provided packages embedded.\n\n``` python\noci_python_image(\n name=\"my-server\",\n base=\":python#slim\",\n repository=\"my-registry.example.com/a-namespace/an-image\",\n\tmain=\"/app/server/start.py\",\n tag=\"latest\",\n packages=[\":my_pex\"]\n)\n```\n\n| Argument | Meaning | Default value |\n|---------------|--------------------------------------------------------------------------------|-------------------------------------------------------|\n| `name` | The target name | Same as any other target, which is the directory name |\n| `base` | The base image to use. Matches the `FROM` directive in a Dockerfile | **Required** |\n| `packages` | Packaged targets to include. The first element will be used as the entrypoint. | `[]` |\n| `python_main` | The main file to run | The last `.pex` in the dependency list |\n| `repository` | Fully qualified repository name | Required when publishing |\n| `tag` | Remote tag to use | Required when publishing |\n| `decsription` | A description of the target | |\n| `tags` | List of tags | `[]` |\n\n### `oci_image_empty`\n\nAn empty base image with no contents at all. This is declared as `//:empty` automatically, but you can use this to create new targets.\n\n``` python\noci_image_empty(\n name=\"empty\",\n)\n```\n\n| Argument | Meaning | Default value |\n|---------------|--------------------------------------------------------------------------------|-------------------------------------------------------|\n| `name` | The target name | Same as any other target, which is the directory name |\n| `decsription` | A description of the target | |\n| `tags` | List of tags | `[]` |\n\n### `oci_build_layer`\n\nRun an image command, and capture the configured output into a layer artifact, that can be injected into other images. This matches the `COPY --from` workflows.\n\noci_build_layer(\n name=\"layer\"\n\tbase=[\":rust-1-70\"],\n packages=[\":files\"],\n env=['RUSTC_OPTS=...'],\n\tcommand=['cd /my-package && cargo build --release'],\n\toutputs=['/my-package/target/release/my-package'],\n)\n```\n\n| Argument | Meaning | Default value |\n|---------------|--------------------------------------------------------------------------------|--------------------------------------------------------|\n| `name` | The target name | Same as any other target, which is the directory name |\n| `packages` | Packaged targets to include. The first element will be used as the entrypoint. | `[]` |\n| `env` | Environment variables to set. Does not support interpolation. | `[]` |\n| `outputs` | Paths to capture into the built layer. | `[]` |\n| `exclude` | Globs to not include in the output. | `[]` |\n| `decsription` | A description of the target | |\n| `output_path` | The output path during `pants package` | A variant generated from the target name and directory |\n| `tags` | List of tags | `[]` |\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2022 Tom Solberg Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "An OCI plugin for the Pants build system",
"version": "0.6.1",
"project_urls": {
"Changelog": "https://github.com/tgolsson/pants-backends/tree/main/pants-plugins/oci/CHANGELOG.md",
"Code": "https://github.com/tgolsson/pants-backends/tree/main/pants-plugins/oci",
"Repository": "https://github.com/tgolsson/pants-backends"
},
"split_keywords": [
"pantsbuild",
"pants",
"docker",
"oci",
"container"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e49f1d83b5af010a0200c583cf27596bea564f05f4ac5cc09eef0dca730490cf",
"md5": "b1c2926fbdb734fd2a9ff066b8bfdb2e",
"sha256": "6fcd4779669a8339af8e165049740880dc7d91be1e62bad5d503dbfd381c55e7"
},
"downloads": -1,
"filename": "pants_backend_oci-0.6.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "b1c2926fbdb734fd2a9ff066b8bfdb2e",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 41456,
"upload_time": "2024-03-28T21:14:40",
"upload_time_iso_8601": "2024-03-28T21:14:40.977121Z",
"url": "https://files.pythonhosted.org/packages/e4/9f/1d83b5af010a0200c583cf27596bea564f05f4ac5cc09eef0dca730490cf/pants_backend_oci-0.6.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e01c5d7fdb3a2130bf3abfc0307253c79065bacd2465703e34626a5003ee905b",
"md5": "13403a2e0ab85cacac17b109e86a9b4f",
"sha256": "d14997dde812ef88ba28e020d4717799bab0a48160cbb6bc04850573f357bc79"
},
"downloads": -1,
"filename": "pants_backend_oci-0.6.1.tar.gz",
"has_sig": false,
"md5_digest": "13403a2e0ab85cacac17b109e86a9b4f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 27614,
"upload_time": "2024-03-28T21:14:43",
"upload_time_iso_8601": "2024-03-28T21:14:43.766786Z",
"url": "https://files.pythonhosted.org/packages/e0/1c/5d7fdb3a2130bf3abfc0307253c79065bacd2465703e34626a5003ee905b/pants_backend_oci-0.6.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-28 21:14:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tgolsson",
"github_project": "pants-backends",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pants-backend-oci"
}
