An opinionated Buildkite plugin for running pipeline steps as Kubernetes Jobs on a cluster with minimal effort.

The plugin tries to stay reasonably compatible with the Docker plugin to make it easy to change pipelines to run on a cluster. It also takes lots of inspiration from the kustomize-job-buildkite-plugin.

Since the step isn't actually performed by the build-agent itself, but in a separately scheduled (and isolated) container, a few things don't work as on a "normal" build-agent.

The build step container will have the buildkite-agent binary mounted at /usr/local/bin/buildkite-agent to allow using the agent subcommands for annotations, metadata and artifacts directly.

This behavior may be disabled by setting mount-buildkite-agent: false in the pipeline.

** Note: ** The user is responsible for making sure the container specified in image contains any external dependencies required by the otherwise statically linked buildkite-agent binary. This includes certificate authorities, and possibly git and ssh depending on how it's being used.

As the build-agent doesn't run in the same container as the actual commands, automatic upload of artifacts specified in artifact_paths won't work. A workaround to this is to run buildkite-agent artifact upload ... as a command in the step itself.

steps:
  - command: "echo 'Hello, World!'"
    plugins:
      - EmbarkStudios/k8s:
          image: alpine

If you want to control how your command is passed to the container, you can use the command parameter on the plugin directly:

steps:
  - plugins:
      - EmbarkStudios/k8s:
          image: "embarkstudios/fortune"
          always-pull: true
          command: ["startrek"]

You can pass in additional environment variables, including values from a Secret:

steps:
  - command:
      - "yarn install"
      - "yarn run test"
    plugins:
      - EmbarkStudios/k8s:
          image: "node:7"
          environment:
            - "MY_SPECIAL_BUT_PUBLIC_VALUE=kittens"
          environment-from-secret:
            - "kitten-secrets"

The name of the container image to use.

Example: golang:1.12.5

Whether to always pull the latest image before running the command. Sets imagePullPolicy on the container. If false, the value IfNotPresent is used.

Default: false

Sets the command for the container. Useful if the container image has an entrypoint, but requires extra arguments.

Note that this has different meaning than in Docker. This sets the args field for the Container.

This option can't be used if your step already has a top-level, non-plugin command option present.

Examples: [ "/bin/mycommand", "-c", "test" ], ["arg1", "arg2"]

Override the image’s default entrypoint.

Note that this has different meaning than in Docker. This sets the command field for the Container.

Example: /my/custom/entrypoint.sh

An array of additional environment variables to pass into to the docker container. Items can be specified as KEY=value.

Example: [ "FOO=bar", "MY_SPECIAL_BUT_PUBLIC_VALUE=kittens" ]

One or more Secrets that should be added to the container as environment variables. Each key in the secret will be exposed as an environment variable. If specified as an array, all listed secrets will be added in order.

Example: my-secrets

One or more Secrets that should be added to the job init container as environment variables. Each key in the secret will be exposed as an environment variable. If specified as an array, all listed secrets will be added in order.

Example: my-secrets

Override the job initContainer. A buildkite-agent binary is expected to exist to do the checkout, along with git and ssh. The default is to use a public image based on the Dockerfile in this repository.

Example: embarkstudios/k8s:1.0.0

Wether to run the container in privileged mode.

The name of the secret containing the buildkite agent token and, optionally, ssh or git credentials used for bootstrapping in the init container.

The key of the secret value containing the buildkite agent token, within the secret specified in secret-name.

The name of the secret containing the git credentials used for checking out source code with HTTPS.

The key of the secret value containing the git credentials used for checking out source code with HTTPS.

The contents of this file will be used as the git credential store file.

The name of the secret containing the git credentials used for checking out source code with SSH.

The key of the secret value containing the SSH key used when checking out source code with SSH as transport.

Mount a host path as a directory inside the container. Must be in the form of /host/path:/some/mount/path. Multiple host paths may be mounted by specifying a list of host/mount pairs.

Example: my-secret:/my/secret

Mount a secret as a directory inside the container. Must be in the form of secretName:/some/mount/path. Multiple secrets may be mounted by specifying a list of secret/mount pairs.

Example: my-secret:/my/secret

The name of the secret containing the buildkite agent token, ssh and git credentials used for bootstrapping in the init container. The key names of the secret are not configurable and as such must contain the following:

  buildkite-agent-token: <token>
  git-credentials: <credentials>
  ssh-key: <sshkey>

This is useful if you have control over secret creation and would like to avoid explicitly providing the key and secret names.

Example: buildkite-secret

Optionally mount a host path to be used as base directory for buildkite builds. This allows local caching and incremental builds using fast local storage.

Should be used with some care, since the actual storage used is outside the control of Kubernetes itself.

Example: /var/lib/buildkite/builds

Optionally mount an existing Persistent Volume Claim used as backing storage for the build.

Optionally mount a host path to be used as git-mirrors path. This enables multiple pipelines to share a single git repository.

Should be used with some care, since the actual storage used is outside the control of Kubernetes itself.

Example: /var/lib/buildkite/builds

Sets cpu request for the build container.

Sets cpu limit for the build container.

Sets memory request for the build container.

Sets memory limit for the build container.

If set to true, the spawned jobs will use the same node affinity and tolerations as the buildkite agent.

Override the working directory to run the command in, inside the container. The default is the build directory where the buildkite bootstrap and git checkout runs.

(Advanced / hack use). Provide a jsonnet function to transform the resulting job manifest.

Example:

patch: |
  function(job) job {
    spec+: {
      template+: {
        spec+: {
          tolerations: [ { key: 'foo', value: 'bar', operator: 'Equal', effect: 'NoSchedule' }, ],
        },
      },
    },
  }

We welcome community contributions to this project.

Please read our Contributor Guide for more information on how to get started.

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.