grim/convey

Start updating the documentation
redux
2021-10-16, Gary Kramlich
738aea24df10
Parents 8c645093c2e3
Children 0accac3db806
Start updating the documentation
3 files changed, 350 insertions(+), 114 deletions(-)
  • +34 -107
    REFERENCE.md
  • +304 -0
    docker/README.md
  • +12 -7
    tasks/README.md
    • --- a/REFERENCE.md Sat Oct 16 04:57:56 2021 -0500
    +++ b/REFERENCE.md Sat Oct 16 04:58:23 2021 -0500
    @@ -1,7 +1,7 @@
    # Configuration
    -Configuring convey is done via a file named `convey.yml`. This file defines
    -the tasks as well as the plans. This document explains how that file is
    +Configuring convey is done via a file named `convey.yml`. This file defines
    +the tasks as well as the plans. This document explains how that file is
    structured and what options are available.
    # Examples
    @@ -13,83 +13,12 @@
    The complete reference for convey.yml can be found below.
    -## required-version
    -
    -The `required-version` field lets you specify a required version of convey
    -to run your `convey.yml`. Ranges are supported according to the semantics
    -defined [here](https://github.com/blang/semver#ranges). If a
    -`required_version` is not specified, convey will always attempt to run the
    -`convey.yml`.
    -
    -## Options
    -
    -The options section lets you fine tune a few things about your configuration.
    -
    -### default-plan
    -
    -`default-plan` is the name of the plan that should be run by default. When not
    -set, this defaults to `default`.
    -
    -### ssh-identities
    -
    -You can specify a list of SSH key fingerprints that are required for your run.
    -This is done by using the `ssh-identities` attribute which is a list of SSH
    -key fingerprints with an option checksum prefix. You can also specify `*` to
    -allow any key that's been added to the `ssh-agent`.
    -
    -`ssh-identities` are also supported in your override file. However, any
    -`ssh-identities` specified in your `convey.yml` will be overridden by the
    -values in the override file; they will not be merged.
    -
    -**NOTE** If running on docker4mac, there is an
    -[issue](https://github.com/docker/for-mac/issues/483) with xhyve (the
    -hypervisor that the Docker daemon runs in) where you can't volume mount the
    -`ssh-agent` socket. You can use this
    -[workaround](https://hub.docker.com/r/uber/ssh-agent-forward/) to expose the
    -`ssh-agent` via an alternative method.
    -
    -#### Examples
    -
    - options:
    - ssh-identities:
    - - ivZaDYamb5xdguIUUVT7DXvXwvE9JLsOkOkR3XAfzeI
    - - SHA256:Efrocgd+rvwjDAnHt2jZAcwDqeka0s8Vv7N3m08cVnA
    -
    -When using `*` you have to quote it because `*` treated specially in `yaml`.
    -
    - options:
    - ssh-identities:
    - - '*'
    -
    -## Extends
    -
    -The extends option allows you to define a base configuration file. The filepath
    -is relative to the current configuration file.
    -
    -The current file will inherit the options, tasks, and plans of the base
    -configuration file. If an option is supplied, or a task or plan with the same
    -name is defined in the current file, it replaces the inherited item.
    -
    -## Tasks
    -
    -The tasks section defines each task. By defining them separately from the
    -plan the tasks can be reused in multiple plans.
    -
    -There are many tasks types which can be chosen by the value of the `type`
    -attribute. See the links below for detailed information on each category of
    -tasks.
    -
    -* [aws](aws/README.md)
    -* [convey](tasks/README.md)
    -* [docker](docker/README.md)
    -* [kubectl](kubectl/README.md)
    -
    ## Environment
    The environment section defines a list of environment variables to set for the
    run.
    -It should be specified in a `NAME` or `NAME=VALUE` format. If no value is
    +It should be specified in a `NAME` or `NAME=VALUE` format. If no value is
    provided, the value of the variable from the host will be provided if it is
    available.
    @@ -104,9 +33,9 @@
    Since there are multiple places where environment variables can be set, they
    must all be merged together before being passed to a task.
    -Environment variables can be set at the `global-base`, `global`,
    -`global-override`, `plan`, `stage`, `task`, and command line levels. The are
    -merged in that order, with the last one taking precedence over the previous.
    +Environment variables can be set at the `config-file`, `plan`, `stage`, `task`,
    +and command line levels. They are merged in that order, with the last one
    +taking precedence over the previous.
    #### Examples
    @@ -118,13 +47,13 @@
    - FOO=bar
    tasks:
    env1:
    - type: docker/run
    - image: alpine:edge
    + type: podman/run
    + image: docker.io/alpine:edge
    environment:
    - FOO=baz
    env2:
    - type: docker/run
    - image: alpine:Edge
    + type: podman/run
    + image: docker.io/alpine:Edge
    plans:
    default:
    stages:
    @@ -132,21 +61,21 @@
    - env1
    - env2
    -In the next example, the stage is overriding the global value. So `env1` still
    -has a value of `baz` for the environment variable `FOO`, while `env2` has a
    -value of `qux`.
    +In the next example, the stage is overriding the config-file value. So `env1`
    +still has a value of `baz` for the environment variable `FOO`, while `env2` has
    +a value of `qux`.
    environment:
    - FOO=bar
    tasks:
    env1:
    - type: docker/run
    - image: alpine:edge
    + type: podman/run
    + image: docker.io/alpine:edge
    environment:
    - FOO=baz
    env2:
    - type: docker/run
    - image: alpine:Edge
    + type: podman/run
    + image: docker.io/alpine:Edge
    plans:
    default:
    stages:
    @@ -177,29 +106,21 @@
    ### Plan
    -Plans themselves are pretty straight forward. They group `stages` with an
    +Plans themselves are pretty straight forward. They group `stages` with an
    optional `environment`.
    ### Attributes
    | Name | Required | Description |
    | ----------- | -------- | ----------- |
    -| environment | | A list of environment variables to set. The should be specified in a `NAME` or `NAME=VALUE` format. If no value is provided, the value of the variable from the host will be provided if it is available. These environment variables will be applied on top of any that were set at the top-level. |
    +| environment | | A list of environment variables to set. They should be specified in a `NAME` or `NAME=VALUE` format. If no value is provided, the value of the variable from the host will be provided if it is available. These environment variables will be applied on top of any that were set at the config-file level. |
    | stages | Yes | A list of `stages` to be run as part of this `plan` in the order that they should be run in. |
    -| merge | | Whether or not to attempt to merge with a plan defined in the parent config file. |
    -
    -If a plan of the same name exists in a parent config file and merge is not set,
    -it will replace the plan in its entirety. If merge is set, then the stages
    -defined in this plan will overwrite stages of the parent plan with the same
    -name. This behavior also applies to environments. It is an error to attempt to
    -merge a stage that does not exist in the parent and new stages cannot be added
    -as their order would not be well defined.
    ----
    ### Stages
    -Stages group `tasks` together into a logical unit. They can be run
    +Stages group `tasks` together into a logical unit. They can be run
    sequentially or concurrently.
    #### Attributes
    @@ -208,27 +129,25 @@
    | ----------- | -------- | ------- | ----------- |
    | enabled | | true | Whether or not to run the stage at all. |
    | concurrent | | false | Whether or not the tasks should be run at the same time. |
    -| environment | | | A list of environment variables to set. The should be specified in a `NAME` or `NAME=VALUE` format. If no value is provided, the value of the variable from the host will be provided if it is available. These environment variables will be applied on top of any that were set at the top-level and the plan level. |
    -| name | | stageN | A name to give the stage.
    -| run | No | on-success | When a stage should be run. Possible values are `on-success`, `on-failure`, or `always`. Defaults to `on-success`. |
    -| tasks | Yes | | A list of task names to be run as part during this stage. If running sequentially they are run in the order that they are provided. |
    +| environment | | | A list of environment variables to set. The should be specified in a `NAME` or `NAME=VALUE` format. If no value is provided, the value of the variable from the host will be provided if it is available. These environment variables will be applied on top of any that were set at the top-level and the plan level. |
    +| name | | the idex of the stage | A name to give the stage.
    +| run | No | on-success | When a stage should be run. Possible values are `on-success`, `on-failure`, or `always`. |
    +| tasks | Yes | | A list of task names to be run as part during this stage. If running sequentially they are run in the order that they are provided. If you are just specifying a single task, you can just pass use it's name not in a list. |
    ----
    ## Meta Plans
    -Meta plans are used to group plans together and run them in serial. This is
    +Meta plans are used to group plans together and run them in serial. This is
    also possible via the command line by specifying multiple plans to run.
    -There is currently no support for nesting meta plans.
    -
    Meta plans contain a single attribute which is the list of `plans` to run.
    ### Attributes
    | Name | Required | Description |
    | ----------- | -------- | ----------- |
    -| plans | Yes | A list of `plans` to run in the order they should be run in. |
    +| plans | Yes | A list of `plans` to run in the order they should be run in. |
    ### Example
    @@ -238,3 +157,11 @@
    - plan1
    - plan2
    - plan3
    +
    +## Tasks
    +
    +The documentation for the available task types can be found below:
    +
    +* [Convey](tasks/README.md)
    +* [Docker](docker/README.md) (deprecate)
    +* [Podman](podman/README.md)
    --- /dev/null Thu Jan 01 00:00:00 1970 +0000
    +++ b/docker/README.md Sat Oct 16 04:58:23 2021 -0500
    @@ -0,0 +1,304 @@
    +# Docker
    +
    +Since version 0.15.0 convey no longer uses Docker and instead uses podman.
    +The Docker tasks are currently still available for backwards compatibility, but
    +will be removed in a future version. The do a best effort to apply their
    +original functionality to the podman tasks but not everything maps 100%. Please
    +see individual task documentation for additional information.
    +
    +----
    +
    +## docker/build
    +
    +> The docker/build task has been deprecated since version 0.15.0. Use the
    +> podman/build task instead.
    +
    +This task will build a container image.
    +
    +### Attributes
    +
    +**NOTE:** arguments and files are not currently mapped into the podman/build
    +task.
    +
    +| Name | Required | Default | Description |
    +| ---------- | -------- | ------- | ----------- |
    +| arguments | | | A list of build arguments to pass to the build. |
    +| dockerfile | Yes | | The dockerfile to build. |
    +| files | | | A list of files that should be made available for the build. |
    +| labels | | | A list of labels to set on the container image being built. |
    +| tag | | | A tag to apply to the image. |
    +| tags | | | A list of tags to be applied to the image. |
    +| target | | | The name of the target to build in a multi stage dockerfile. |
    +
    +### Example
    +
    + clean:
    + type: docker/build
    + dockerfile: Dockerfile
    + tag: myimage:latest
    +
    +----
    +
    +## docker/environment
    +
    +> The docker/build task has been deprecated and has no replacement.
    +
    +The functionality of this task has been removed and the task now just fails.
    +If you have a use case for this task and would like to keep it, please file
    +and issue in our issue tracker.
    +
    +----
    +
    +## docker/export
    +
    +> The docker/export task has been deprecated since version 0.15.0. Use the
    +> convey/export task instead.
    +
    +This task will export files from the workspace to the host filesystem relative
    +to the convey.yml used for the run.
    +
    +### Attributes
    +
    +| Name | Required | Default | Description |
    +| ------ | -------- | ------- | ----------- |
    +| files | Yes | | A single filename, source:destination, or a list of filenames and/or source:destinations. |
    +
    +### Examples
    +
    + export-single:
    + type: docker/export
    + files: filename1
    +
    + export-multiple:
    + type: docker/export
    + files:
    + - logo.png
    + - binary:binary-linux-x86_64
    +
    +----
    +
    +## docker/import
    +
    +> The docker/import task has been deprecated since version 0.15.0. Use the
    +> convey/import task instead.
    +
    +This task will import files from the host filesystem relative to the convey.yml
    +used for the run and put them into the workspace.
    +
    +### Attributes
    +
    +| Name | Required | Default | Description |
    +| ------ | -------- | ------- | ----------- |
    +| files | Yes | | A single filename, source:destination, or a list of filenames and/or source:destinations. |
    +
    +### Examples
    +
    + import-single:
    + type: docker/import
    + files: filename1
    +
    + import-multiple:
    + type: docker/import
    + files:
    + - Dockerfile
    + - src:source
    +
    +----
    +
    +## docker/login
    +
    +> The docker/login task has been deprecated since version 0.15.0. Use the
    +> podman/login task instead.
    +
    +This task allows you to authorize to a container registry.
    +
    +### Attributes
    +
    +| Name | Required | Default | Description |
    +| --------- | -------- | --------- | ----------- |
    +| username | Yes | | The username to use. |
    +| password | Yes | | The password to use. |
    +| server | | docker.io | The registry to login to. |
    +
    +### Example
    +
    + registry-login:
    + type: docker/login
    + username: superuser1
    + password: abc123
    +
    +----
    +
    +## docker/logout
    +
    +> The docker/logout task has been deprecated since version 0.15.0. Use the
    +> podman/logout task instead.
    +
    +This task allows you to unauthenticate from a container registry.
    +
    +### Attributes
    +
    +| Name | Required | Default | Description |
    +| --------- | -------- | --------- | ----------- |
    +| server | | docker.io | The registry to logout of. |
    +
    +### Example
    +
    + registry-logout:
    + type: docker/logout
    + server: regsitry.my.domain:5000
    +
    +----
    +
    +### docker/pull
    +
    +> The docker/pull task has been deprecated since version 0.15.0. Use the
    +> podman/pull task instead.
    +
    +This task allows you to pull down a container image. If the image is private,
    +be use to run a `docker/login` task first.
    +
    +### Attributes
    +
    +| Name | Required | Default | Description |
    +| ------ | -------- | ------- | ----------- |
    +| image | | | The name of the image include the tag. |
    +| images | | | A list of image names 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
    +
    + pull-alpine:
    + type: docker/pull
    + image: gliderlabs/alpine:edge
    +
    +----
    +
    +### docker/push
    +
    +> The docker/push task has been deprecated since version 0.15.0. Use the
    +> podman/push task instead.
    +
    +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 `docker/login` task
    +first.
    +
    +### Attributes
    +
    +| Name | Required | Default | Description |
    +| ------ | -------- | ------- | ----------- |
    +| image | | | The name of the image include the tag. |
    +| images | | | A list of image names 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: docker/push
    + images:
    + - registry.my.domain:5000/newimage:main-latest
    + - registry.my.domain:5000/newimage:main-deadbeef
    +
    +----
    +
    +## docker/remove
    +
    +> The docker/remove task has been deprecated since version 0.15.0. Use the
    +> podman/remove task instead.
    +
    +This task will remove an image from the local machine.
    +
    +### Attributes
    +
    +
    +| Name | Required | Default | Description |
    +| ------ | -------- | ------- | ----------- |
    +| image | | | The name of the image include the tag. |
    +| images | | | 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: docker/remove
    + images:
    + - registry.my.domain:5000/newimage:main-latest
    + - registry.my.domain:5000/newimage:main-deadbeef
    +
    +----
    +
    +## docker/run
    +
    +> The docker/run task has been deprecated since version 0.15.0. Use the
    +> podman/run task instead.
    +
    +This task will run a container with the workspace mounted.
    +
    +### Attributes
    +
    +**NOTE:** the detach and healthcheck attributes are not mapped to the
    +podman/run task and are not expected to be in the future. If you have a use
    +case for this, please open an issue on our issue tracker.
    +
    +| Name | Required | Default | Description |
    +| ----------- | -------- | ------- | ----------- |
    +| command | | | The command to run in the container. This is only necessary if the image does not provide a command by default. |
    +| detach | | false | This is deprecated and no longer support. |
    +| 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. |
    +| healthcheck | | | THis is deprecated and no longer support. |
    +| hostname | | | A custom hostname to set inside the container. |
    +| image | Yes | | The image include the registry and tag to run. |
    +| labels | | | A list of labels to set on the image being built. |
    +| 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: docker/run
    + image: golang:onbuild
    +
    +A basic example using a a standard image to do something else.
    +
    + download-file:
    + type: docker/run
    + image: debian:jessie-slim
    + script:
    + - wget https://somedomain.tld/file1
    + - wget https://somedomain.tld/file1.sha256sum
    + - sha256sum -c file1.sha256sum
    +
    +----
    +
    +## docker/tag
    +
    +> The docker/tag task has been deprecated since version 0.15.0. Use the
    +> podman/tag task instead.
    +
    +This task will tag existing images on the host.
    +
    +### Attributes
    +
    +| Name | Required | Default | Description |
    +| ---------- | -------- | ------- | ----------- |
    +| source | Yes | | The full source image including the registry and tag to tag. |
    +| detination | Yes | | The destination tag include the registry and tag to create. |
    +
    +### Example
    +
    + tag-dev:
    + type: docker/tag
    + source: registry.my.domain:5000/newimage:latest
    + destination: registry.my.domain:5000/newimage:dev
    --- a/tasks/README.md Sat Oct 16 04:57:56 2021 -0500
    +++ b/tasks/README.md Sat Oct 16 04:58:23 2021 -0500
    @@ -6,7 +6,8 @@
    ## convey/clean Task
    -A clean task will remove files from the host relative and limited to the directory where the convey.yml for the run.
    +A clean task will remove files from the host relative and limited to the
    +directory containing the convey.yml for the run.
    ### Attributes
    @@ -27,13 +28,14 @@
    ## convey/export Task
    -An export task will move files from the workspace to the host underneath the directory where the convey.yml file was found.
    +An export task will move files from the workspace to the host underneath the
    +directory containing the convey.yml file was found.
    ### Attributes
    | Name | Required | Default | Description |
    | --------- | -------- | ------- | ----------- |
    -| files | Yes | | A single filename or a list of files to copy from the workspace to the host. Files can be specified in one of two forms which can be mixed. The first is `source:destination` and the other is `filename` where filename will be used for both the host and the volume. |
    +| files | Yes | | A single filename or a list of files to copy from the workspace to the host. Files can be specified in one of two forms which can be mixed. The first is `source:destination` and the other is `filename` where filename will be used for both the host and the volume. |
    ### Examples
    @@ -51,7 +53,8 @@
    ## convey/fail Task
    -The fail task just automatically fails. It's similar to convey/noop in that it's mostly used for debugging.
    +The fail task just automatically fails. It's similar to `convey/noop` in that
    +it's mostly used for debugging.
    ### Attributes
    @@ -66,13 +69,15 @@
    ## convey/import Task
    -An import task copies files from the host to the workspace. It has one required attribute named files. This is a list of files relative to the directory the convey.yml file that will be copied into the workspace.
    +An import task copies files from the host to the workspace. It has one required
    +attribute named files. This is a list of files relative to the directory
    +containing the convey.yml file that will be copied into the workspace.
    ### Attributes
    | Name | Required | Default | Description |
    | ----- | -------- | ------- | ----------- |
    -| files | Yes | | A single filename or a list of files to copy from the host to the workspace. Files can be specified in one of two forms which can be mixed. The first is `source:destination` and the other is `filename` where filename will be used for both the host and the volume. |
    +| files | Yes | | A single filename or a list of files to copy from the host to the workspace. Files can be specified in one of two forms which can be mixed. The first is `source:destination` and the other is `filename` where filename will be used for both the host and the volume. |
    ### Examples
    @@ -90,7 +95,7 @@
    ## convey/noop Task
    -A noop task does nothing. It is a "No Operation" task. It's used primarily in
    +A noop task does nothing. It is a "No Operation" task. It's used primarily in
    testing, but could be used for stubbing stuff out or debugging.
    ### Attributes