Skip to content

Latest commit

 

History

History
310 lines (204 loc) · 8.67 KB

06-01_pull-policy.md

File metadata and controls

310 lines (204 loc) · 8.67 KB
Raw

Pull Policy

Key Value
Author(s) Jordan.Brockopp
Reviewers Neal.Coleman, David.May, Emmanuel.Meinen, Kelly.Merrick, David.Vader
Date June 1st, 2020
Status Completed

Background

Please provide a summary of the new feature, redesign or refactor:

This enhancement will enable the ability to control when an image is retrieved to be used in a pipeline.

By expanding upon the existing pull YAML declaration, we can add more flexibility in how the worker will capture the images to be executed in a pipeline.

It will also give customers the flexibility to use images that are built during the execution of the pipeline in a later, subsequent step.

Please briefly answer the following questions:

  1. Why is this required?
  • provide compatible functionality with existing CI solutions
  • provide greater control of how and when images will be retrieved for a pipeline
  • enable customers to use an image that is built during the execution of the pipeline
  1. If this is a redesign or refactor, what issues exist in the current implementation?

Currently, users are unable to use an image that is built directly in the pipeline.

In the below design, the pipeline would fail due to the worker attempting to pull all images before executing the pipeline.

Even if the image does exist, and a customer wants to overwrite the existing image with the one built in their pipeline, they would still end up running the pipeline with the old image.

version: "1"

steps:
  - name: publish
    image: target/vela-docker:v0.2.1
    pull: true
    parameters:
      registry: index.docker.io
      repo: index.docker.io/octocat/hello-world
      tags: [ myNewTag ]

  - name: test
    image: index.docker.io/octocat/hello-world:myNewTag
    pull: true
    commands:
      - echo 'this step will fail'
  1. Are there any other workarounds, and if so, what are the drawbacks?

N/A

  1. Are there any related issues? Please provide them below if any exist.

N/A

Design

Please describe your solution to the proposal. This includes, but is not limited to:

  • new/updated endpoints or url paths
  • new/updated configuration variables (environment, flags, files, etc.)
  • performance and user experience tradeoffs
  • security concerns or assumptions
  • examples or (pseudo) code snippets

Expand the existing pull YAML declaration to allow other configurations beyond "pull or don't pull".

5 policies will exist:

  • always (equal to the old true policy)
  • not_present (default)
  • on_start
  • never
  • true (for backwards compatibility)

Backwards Compatibility

  • pull will remain an optional configuration

All pipelines that exist in Vela today will not need to be modified for this enhancement.

This is because the new policies that can be applied will be compatible with the old policies.

  • providing pull: true == pull: always
  • not providing pull: true == pull: not_present
  • pull: not_present will be the default so you can omit providing it
version: "1"

steps:
  - name: old-pull-policy
    image: alpine:latest
    pull: true
    commands:
      - echo "example of old pull true setup"

  - name: new-pull-policy
    image: alpine:latest
    pull: always
    commands:
      - echo "example of new pull true setup"

Always

The always policy will be the functional equivalent of the old, deprecated true policy.

Using this policy will instruct the worker to pull the image, even if it already exists locally.

version: "1"

steps:
  - name: pull-always
    image: alpine:latest
    # pull policy declaration
    pull: always
    commands:
      - echo "this will always pull the latest tag of the alpine image"

Not Present

The not_present policy will be the functional equivalent of omitting the pull YAML declaration.

Using this policy will instruct the worker to pull the image only if it doesn't already exist locally.

NOTE: This will be the new default policy.

version: "1"

steps:
  - name: pull-not_present
    image: alpine:latest
    # pull policy declaration
    pull: not_present
    commands:
      - echo "this will pull the latest tag of the alpine image if it doesn't exist locally"

Never

The never policy will be a new concept introduced with this enhancement.

The intention of this policy is to enforce the ability of only using an image from the existing worker cache.

This can allow Vela admins to guarantee a specific version of an image being executed across all pipelines.

Using this policy will instruct the worker to never pull the image

NOTE: If the image doesn't already exist locally, this will cause a pipeline failure.

version: "1"

steps:
  - name: pull-never
    image: alpine:latest
    # pull policy declaration
    pull: never
    commands:
      - echo "this will never pull the latest tag of the alpine image"

On Start

The on_start policy will be a new concept introduced with this enhancement.

The intention of this policy is to enable using an image that was built during the execution of the pipeline.

Using this policy will instruct the worker to pull the image before starting the container.

version: "1"

steps:
  - name: pull-on_start
    image: alpine:latest
    # pull policy declaration
    pull: on_start
    commands:
      - echo "this will pull the latest tag of the alpine image at container startup"

True

The true policy will be the old, deprecated functional equivalent of the always policy.

Using this policy will instruct the worker to pull the image, even if it already exists locally.

This policy will only be here for backwards compatibility purpose.

NOTE: This policy should be planned for removal in a future release.

version: "1"

steps:
  - name: pull-true
    image: alpine:latest
    # pull policy declaration
    pull: true
    commands:
      - echo "this is the old deprecated form of pull always"

Implementation

Please briefly answer the following questions:

  1. Is this something you plan to implement yourself?

Yes

  1. What's the estimated time to completion?

2 weeks

Please provide all tasks (gists, issues, pull requests, etc.) completed to implement the design:

  • Implement always, not_present, never, on_start, true constants in go-vela/types/constants
  • Implement a PullPolicy type in go-vela/types/pipeline
  • Implement a PullPolicy type in go-vela/types/yaml
  • The YAML pull declaration will be used to control the configuration for the PullPolicy.
  • The not_present policy will be the new default for all steps.

Questions

Please list any questions you may have:

N/A