The following plugin provides functionality available through Pipeline-compatible steps. Read more about how to integrate steps into your Pipeline in the Steps section of the Pipeline Syntax page.

For a list of other such plugins, see the Pipeline Steps Reference page.

Kubernetes Ephemeral Container Plugin

View this plugin on the Plugins site

withEphemeralContainer: Define an Ephemeral Container to add to the current Pod

Add ephemeral container to the current Kubernetes agent Pod and run some steps in the context of that container.
  • image : String

    Container image reference for the container. The image must have a shell available (i.e. `sh`).

    If the image defines an entrypoint it must be able to accept and execute a command and arguments. Jenkins must be able to stop the container and to do so it passes a process monitor command to know when to exit the container. If the image entrypoint to not perform the monitor task the ephemeral container may not work correctly.

    Configure an empty command list to disable the entrypoint.

    Note: Windows containers are not supported.

  • alwaysPullImage : boolean (optional)
    If ticked, the latest version of the image will be pulled every time it is used. See Images - Kubernetes for the default Kubernetes behaviour.
  • command : Array / List of String (optional)
    • commandLine : String (optional)

      Override the image entrypoint.

      If an empty array, disable the default image entrypoint with the Jenkins monitor command.

      If a non-empty command is provided, it must be able to accept a monitor command and arguments which must be executed. If entrypoint ignores the Jenkins provided monitor command the step may either exit early or failed to be terminated.

      sh '''#!/bin/bash
# do some custom entrypoint stuff

# execute monitor command provided by jenkins
exec "$@"
'''
    • envVars (optional)
      The environment variables to pass to the container.
        Array / List of Nested Choice of Objects
      • containerEnvVar
        • key : String
          The environment variable key.
        • value : String
          The environment variable value.
      • envVar
        • key : String
          The environment variable key.
        • value : String
          The environment variable value.
      • podEnvVar
        • key : String
          The environment variable key.
        • value : String
          The environment variable value.
      • secretEnvVar
        • key : String
          The environment variable key.
        • secretName : String
          Name of secret to lookup from Kubernetes.
        • secretKey : String
          Key of secret to lookup from Kubernetes.
        • optional : boolean
          Whether this secret is optional.
    • runAsGroup : String (optional)

      Specify the gid to run as. Defaults to the jnlp container group.

      Must be a number, greater or equal to 0

      If not set it will be inherited from agent current context. For example, if a nested withEphemeralContainer step, it will inherit from its parent.

    • runAsUser : String (optional)

      Specify the uid to run as. Defaults to the jnlp container user.

      Must be a number, greater or equal to 0.

      If not set it will be inherited from agent current context. For example, if a nested withEphemeralContainer step, it will inherit from its parent.

    • shell : String (optional)

      Specifies a shell which will run inside the container and process requests from Jenkins to run executables, set environment variables, and similar infrastructure.

      This does not affect the shell used to run user code, such as sh steps. To run your scripts with a specific shell on Linux, use an interpreter line:

      sh '''#!/bin/bash
    for x in {0..9}; do echo x; done
    '''

      or just use a subprocess and an externally versioned script:

      sh 'bash ci.sh'

      For a pod running on Linux, defaults to sh, which should be in $PATH. Should not generally be overridden.

    • targetContainer : String (optional)
      If set, the name of the container from PodSpec that this ephemeral container targets. The ephemeral container will be run in the namespaces (IPC, PID, etc.) of this container. If not set then the ephemeral container uses the namespaces configured in the Pod spec. The container runtime must implement support for this feature. If the runtime does not support namespace targeting then the result of setting this field is undefined.

    ephemeralContainer: Define an Ephemeral Container to add to the current Pod

    Add ephemeral container to the current Kubernetes agent Pod and run some steps in the context of that container.
    • image : String

      Container image reference for the container. The image must have a shell available (i.e. `sh`).

      If the image defines an entrypoint it must be able to accept and execute a command and arguments. Jenkins must be able to stop the container and to do so it passes a process monitor command to know when to exit the container. If the image entrypoint to not perform the monitor task the ephemeral container may not work correctly.

      Configure an empty command list to disable the entrypoint.

      Note: Windows containers are not supported.

    • alwaysPullImage : boolean (optional)
      If ticked, the latest version of the image will be pulled every time it is used. See Images - Kubernetes for the default Kubernetes behaviour.
    • command : Array / List of String (optional)
      • commandLine : String (optional)

        Override the image entrypoint.

        If an empty array, disable the default image entrypoint with the Jenkins monitor command.

        If a non-empty command is provided, it must be able to accept a monitor command and arguments which must be executed. If entrypoint ignores the Jenkins provided monitor command the step may either exit early or failed to be terminated.

        sh '''#!/bin/bash
# do some custom entrypoint stuff

# execute monitor command provided by jenkins
exec "$@"
'''
      • envVars (optional)
        The environment variables to pass to the container.
          Array / List of Nested Choice of Objects
        • containerEnvVar
          • key : String
            The environment variable key.
          • value : String
            The environment variable value.
        • envVar
          • key : String
            The environment variable key.
          • value : String
            The environment variable value.
        • podEnvVar
          • key : String
            The environment variable key.
          • value : String
            The environment variable value.
        • secretEnvVar
          • key : String
            The environment variable key.
          • secretName : String
            Name of secret to lookup from Kubernetes.
          • secretKey : String
            Key of secret to lookup from Kubernetes.
          • optional : boolean
            Whether this secret is optional.
      • runAsGroup : String (optional)

        Specify the gid to run as. Defaults to the jnlp container group.

        Must be a number, greater or equal to 0

        If not set it will be inherited from agent current context. For example, if a nested withEphemeralContainer step, it will inherit from its parent.

      • runAsUser : String (optional)

        Specify the uid to run as. Defaults to the jnlp container user.

        Must be a number, greater or equal to 0.

        If not set it will be inherited from agent current context. For example, if a nested withEphemeralContainer step, it will inherit from its parent.

      • shell : String (optional)

        Specifies a shell which will run inside the container and process requests from Jenkins to run executables, set environment variables, and similar infrastructure.

        This does not affect the shell used to run user code, such as sh steps. To run your scripts with a specific shell on Linux, use an interpreter line:

        sh '''#!/bin/bash
    for x in {0..9}; do echo x; done
    '''

        or just use a subprocess and an externally versioned script:

        sh 'bash ci.sh'

        For a pod running on Linux, defaults to sh, which should be in $PATH. Should not generally be overridden.

      • targetContainer : String (optional)
        If set, the name of the container from PodSpec that this ephemeral container targets. The ephemeral container will be run in the namespaces (IPC, PID, etc.) of this container. If not set then the ephemeral container uses the namespaces configured in the Pod spec. The container runtime must implement support for this feature. If the runtime does not support namespace targeting then the result of setting this field is undefined.

      Was this page helpful?

      Please submit your feedback about this page through this quick form.

      Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?

          


      See existing feedback here.