Using a Custom Runtime Image

JFrog Pipelines Documentation
Products
JFrog Pipelines
Content Type
User Guide
ft:sourceType
Paligo

In some cases, our standard images library might not satisfy your requirements, or you might have an internal image you want to use for step execution or you may want to use our standard images library with specific settings. Using your own custom image gives you better control over what is installed on the runtime images. It can also speed up step execution since you can pre-install dependencies into the image.

You can configure a custom runtime image by using the configuration shown below. This can be specified at a pipeline or step level. If specified at both levels, the step configuration will take precedence.

pipelines:
  - name: pipe1
    configuration: 
      runtime:       
        type: image
        image:
          custom:
            name: <string>                        # imageRepo/imageName format
            tag: <string>                         # version tag of the initial version of the Docker image
            options: "-e HOME=/root"          # Docker options
            autoPull: <boolean>                   # default true; pulls image before run
            registry: <integration>       # if custom image is private, an integration is required for authentication
            sourceRepository: <path>      # may be required if registry is Artifactory. e.g. docker-local
            region: <string>              # required if registry is AWS. e.g. us-east-1

Tag

Description

name

This is the fully qualified name of the Docker image.

tag

This is the Docker image tag you want to use.

options

This is any Docker option you want to use in the docker run command. You also need to include the$HOMEenvironment variable as shown if it is not already set in your image.

autopull

This is an option to automatically pull the image to the machine running the step. Defaults to true.

If your custom image is private, you will also need to create an integration with credentials for your Docker registry, and set additional values in the config:

Tag

Description

registry

This is the friendly name of your Docker registry integration. Supported integration types are Artifactory or JFrog Platform Access Token Integration , Docker Registry, AWS Keys, and Google Cloud.

sourceRepository

The is not used with JFrog CLI v2.

This is only needed if your Docker registry is Artifactory and the pipeline is configured to use JFrog CLI v1. It is the name of the Docker registry on Artifactory.

region

This is only required if your Docker registry is AWS ECR.

Examples

Example 1

pipelines:
  - name: pipe1
    configuration: 
      runtime:       
        type: image
        image:
          custom:
            name: docker/jfrog_win
            tag: latest
            options: "-e HOME=/root"
            autoPull: false
            registry: PSSG_DockerRegistry

Example 2 - Artifactory registry

pipelines:
  - name: pipe2
    configuration: 
      runtime:       
        type: image
        image:
          custom:
            name: ubuntu
            tag: latest
            registry: myArtifactory
            sourceRepository: docker-local

Example 3 - AWS registry

pipelines:
  - name: pipe3
    configuration: 
      runtime:       
        type: image_aws
        image:
          custom:
            name: 541601.dkr.ecr.us-east-1.amazonaws.com/jfbeta
            tag: latest
            autoPull: false
            registry: AWS
            region: us-east-1
Minimum Requirements for Linux

Any custom runtime image specified for a step that will run in a Linux host node (Ubuntu, CentOS, or RHEL) needs to include this minimum set of components:

  • bash

  • /proc/sys/kernel/random/uuid

  • sed

  • GNU grep

  • ssh

  • coreutils

    • date

    • mkdir

    • cp

    • mv

    • touch

    • seq

    • cat

    • basename (for users usingsend_notification (email)command)

    • rm

    • uniq (for users usingcompare_gitcommand)

    • split (for users usingencrypt_string,decrypt_string,encrypt_file,decrypt_filecommands)

  • jfrog (when using an Artifactory integration or in a native step)

  • jq

  • awk (for users usingcompare_gitcommand)

  • git (for users usingcompare_gitcommand or GitRepo resources))

  • gettext (for users usingreplace_envs,send_notification (email)commands)

    • envsubst

  • curl (for users usingsend_notificationcommand)

  • base64 (for users usingsend_notification (email),encrypt_string,decrypt_string,encrypt_file,decrypt_filecommands)

  • openssl (for users using encrypt_string,decrypt_string,encrypt_file,decrypt_file commands)

Minimum Requirements for Windows Server

Any custom runtime image specified for a step that will run in a Windows Server host node needs to include this minimum set of components:

  • PowerShell 5

  • jq (for users using replicate_resource or send_notification commands)

  • git (for users using compare_git command or GitRepo resources)

  • openssl (for users using encrypt_string, decrypt_string, encrypt_file, decrypt_file commands)