grim/convey

Add documentation for the podman tasks
redux
2021-10-16, Gary Kramlich
fd65c6d6f2ab
Parents 6abd7f123bd6
Children 18b916dada5e
Add documentation for the podman tasks
1 files changed, 193 insertions(+), 0 deletions(-)
  • +193 -0
    podman/README.md
    • --- /dev/null Thu Jan 01 00:00:00 1970 +0000
    +++ b/podman/README.md Sat Oct 16 05:48:53 2021 -0500
    @@ -0,0 +1,193 @@
    +# Podman
    +
    +Podman is a container runtime that runs daemonless as a normal user. It has
    +been adopted as the only container run time since convey 0.15.0.
    +
    +----
    +
    +## podman/build
    +
    +This task will build a container image.
    +
    +### Attributes
    +
    +| Name | Required | Default | Description |
    +| ------------- | -------- | ------------------- | ----------- |
    +| annotations | | | A list of annotations for the container image. |
    +| containerfile | Yes | | The containerfile to build. |
    +| context | | ${CONVEY_WORKSPACE} | The context to pass to podman build. This path needs to build under the convery workspace which means all files for the build must first be imported into the workspace. |
    +| tags | | | A list of tags or a single tag to be applied to the image. |
    +| target | | | The name of the target to build in a multi stage containerfile. |
    +
    +### Example
    +
    + build:
    + type: podman/build
    + containerfile: Dockerfile
    + tags: myimage:latest
    +
    +----
    +
    +## podman/login
    +
    +This task allows you to authorize to a container registry.
    +
    +### Attributes
    +
    +| Name | Required | Default | Description |
    +| --------- | -------- | --------- | ----------- |
    +| password | Yes | | The password to use. |
    +| registry | | docker.io | The registry to login to. |
    +| username | Yes | | The username to use. |
    +
    +### Example
    +
    + registry-login:
    + type: podman/login
    + username: superuser1
    + password: abc123
    +
    +----
    +
    +## podman/logout
    +
    +This task allows you to unauthenticate from a container registry.
    +
    +### Attributes
    +
    +| Name | Required | Default | Description |
    +| -------- | -------- | --------- | ----------- |
    +| registry | | docker.io | The registry to logout of. |
    +
    +### Example
    +
    + registry-logout:
    + type: podman/logout
    + registry: regsitry.my.domain:5000
    +
    +----
    +
    +### podman/pull
    +
    +This task allows you to pull down a container image. If the image is private,
    +be use to run a `podman/login` task first.
    +
    +### Attributes
    +
    +| Name | Required | Default | Description |
    +| ---- | -------- | ------- | ----------- |
    +| tags | Yes | | A list of image names or a single image name including the tags. |
    +
    +### Example
    +
    + pull-alpine:
    + type: podman/pull
    + tags: gliderlabs/alpine:edge
    +
    +----
    +
    +### podman/push
    +
    +This task allows you to push a local container image to a registry. If the
    +repository on the registry is private, be use to run a `podman/login` task
    +first.
    +
    +### Attributes
    +
    +| Name | Required | Default | Description |
    +| ---- | -------- | ------- | ----------- |
    +| tags | Yes | | A list of image names or a single image name including the tags. |
    +
    +At least one image must be supplied by either the `image` or `images`
    +attribute. If both are specified, `image` will be prepended to the list from
    +`images`.
    +
    +### Example
    +
    + push-images:
    + type: podman/push
    + tags:
    + - registry.my.domain:5000/newimage:main-latest
    + - registry.my.domain:5000/newimage:main-deadbeef
    +
    +----
    +
    +## podman/remove
    +
    +This task will remove an image from the local machine.
    +
    +### Attributes
    +
    +
    +| Name | Required | Default | Description |
    +| ----- | -------- | ------- | ----------- |
    +| tags | | | A list of image names including the tags. |
    +| quiet | | false | True if a missing image should not count as a failure. |
    +
    +### Example
    +
    + remove-image:
    + type: podman/remove
    + tags:
    + - registry.my.domain:5000/newimage:main-latest
    + - registry.my.domain:5000/newimage:main-deadbeef
    +
    +----
    +
    +## podman/run
    +
    +This task will run a container with the workspace mounted.
    +
    +### Attributes
    +
    +| Name | Required | Default | Description |
    +| ----------- | -------- | ------- | ----------- |
    +| annotations | | | A list of annotations to set on the container being run. |
    +| command | | | The command to run in the container. This is only necessary if the image does not provide a command by default. |
    +| entrypoint | | | The entrypoint to use for the container. This is only necessary if the image does not provide on by default or if you want to override the images default entrypoint. |
    +| environment | | | A list of environment variables to set. This should be specified in a `NAME` or `NAME=VALUE` format. |
    +| hostname | | | A custom hostname to set inside the container. |
    +| image | Yes | | The image include the registry and tag to run. |
    +| script | | | A list of commands to run inside of the container. |
    +| shell | | | The shell to use with the script attribute above. |
    +| user | | | The user to run the container as. |
    +| workdir | | | The working directory inside the container. |
    +| workspace | | | The path to mount the convey workspace at inside of the container. |
    +
    +### Example
    +
    +A basic example where the image knows everything to do.
    +
    + build-golang:
    + type: podman/run
    + image: golang:onbuild
    +
    +A basic example using a a standard image to do something else.
    +
    + download-file:
    + type: podman/run
    + image: debian:bookworm
    + script:
    + - wget https://somedomain.tld/file1
    + - wget https://somedomain.tld/file1.sha256sum
    + - sha256sum -c file1.sha256sum
    +
    +----
    +
    +## podman/tag
    +
    +This task will tag existing images on the host.
    +
    +### Attributes
    +
    +| Name | Required | Default | Description |
    +| ------- | -------- | ------- | ----------- |
    +| image | Yes | | The full source image including the registry and tag to tag. |
    +| targets | Yes | | The destination tag include the registry and tag to create. |
    +
    +### Example
    +
    + tag-dev:
    + type: podman/tag
    + image: registry.my.domain:5000/newimage:latest
    + targets: registry.my.domain:5000/newimage:dev