Cloud customer?
 Upgrade in MyJFrog >

Search





Overview

Resources typically contain information needed for a step in a pipeline to execute and can also be used to store information produced by a step. Resources defined should be unique across all the pipelines. Because of that they also provide the way to link pipelines. 


Commonly used examples of a resource are:

  • A repository in your source code control system (e.g., GitHub)
  • A file on a remote file server
  • A Docker image
  • A release bundle for JFrog Distribution
  • A cluster for container orchestration



Resource Definition

Resources are defined in a pipeline config under the resources tag, as shown below. Not all sections are required by all resources.

resources:
  - name:               <string>
    type:               <resource type name>
	configuration:
      <as required by type>
TagDescription of usageRequired/Optional
name

An alphanumeric string (underscores are permitted) that makes it easy to infer what the resource represents, e.g., aws_creds to represent AWS keys. This name is used to refer to the resource in steps, and must be unique across all repositories in your JFrog Pipelines environment.

Required
type

Name of the resource type that this resource is an instance of. A list of all types is below.

Required
configuration

Specifies configuration settings, which vary for each type of resource.

Commonly included in this block is a setting that assigns by its name an integration through which the resource will be accessed. The integration must be compatible with the type of the resource. The name of the integration field will vary by the resource. 

Required


Using Resources

Resources can be inputs and outputs of steps in a pipeline. They can be used by steps in these ways:

Inputs

When specified in a step in the inputResources section, the resource is an input for a step. The resource can also be referred to by its name as an argument in shell commands that the step executes.

A resource version will automatically initiate the execution of that step that has that resource as input resource. 

For example, when a Step specifies a GitRepo resource,  any new code commit to that Git repository will automatically cause that step to execute.

If a step that specifies an image resource and trigger is set to false, the step is executed, it will use the latest version of the resource during the execution. 

Steps that have input resources from other pipelines trigger a run of the pipeline when the resource is updated. By default, input resources that were an output resource of another step in the same run will run whether or not the resource is updated. To skip steps in the same run when input resources are not updated, newVersionOnly may be added to the input resource.

Outputs

When specified as the output of a step in an outputResources tag, the resource receives the output of the native step. The resource can also be referred to by its name as an argument in shell commands that the step executes. 

Environment Variables

A step that specifies a resource in inputresources can access the resource and its attributes through environment variables. The form of the environment variable is:

res_<resource name>_<tag>

You can also access an integration that is specified in the resource through an environment variable, whose form is:

res_<resource_name>_<integration tag name>_<tag>

For example, if the definition of a GitRepo resource named app_gitrepo is:

resources:
  - name: app_gitRepo
    type: GitRepo
    configuration:
      path: user1/repo1
      gitProvider: myGitProvider


Then the following environment variables will be available to a step that uses the app_gitRepo as an input:

Environment VariableResultDescription
res_app_gitRepo_pathuser1/repo1Returns the path attribute of the app_gitRepo resource
res_app_gitRepo_gitProvider_url
Returns url of the Git Provider of the app_gitRepo resource


The example step shows how these environment variables might be used to send notifications:

steps:
  - name: build_app
    type: MvnBuild
    configuration:
      sourceLocation: .
      mvnCommand: clean install
      configFileLocation: .
      inputResources:
        - name: app_gitRepo	            # Use the app_gitRepo resource
   execution:
     onSuccess:
       - send_notification notifySlack --text "Maven build completed for $res_app_gitRepo_path at $res_app_gitRepo_gitProvider_url"
     onFailure:
       - send_notification notifySlack --text "Maven build FAILED for $res_app_gitRepo_path at $res_app_gitRepo_gitProvider_url"

Arrays

For arrays within resources (e.g. VmCluster):

res_<resource name>_<array heading>_len     (this tells you how many entries in array)
res_<resource name>_<array heading>_0
res_<resource name>_<array heading>_1
res_<resource name>_<array heading>_2

For object arrays within resources (e.g. DistributionRule):

res_<resource name>_<array heading>_len     (this tells you how many entries in array)
res_<resource name>_<array heading>_0_<tag>
res_<resource name>_<array heading>_1_<tag>

State Information

Steps can store any key-value pair data in a resource using the write_output utility function. Those values held by the resource can then be referenced as environment variables by any subsequently executing step that uses that resource as an input. In this way, a step can pass information to another step in the run of the pipeline.

The environment variable for the stored value will be of the form res_<resource name>_<key name>.  

For example, the following write_output command:

write_output myResource "description=\"hello world\""

will store the string value of description in the resource. Any step can then access that value stored in myResource through the environment variable $res_myResource_description.

For more information, see Creating Stateful Pipelines.




Resource types

These are the types of resources that JFrog Pipelines supports:

  • AqlAn Aql resource specifies an Artifactory query using Artifactory Query Language. 
  • BuildInfoA BuildInfo resource is the metadata associated with a build in Artifactory.
  • CronTriggerA CronTrigger is used as an inputResource to a step to trigger execution of the step at a scheduled time.
  • DistributionRuleA DistributionRule resource is the set of Destination rules that can be applied to distributing a release bundle using JFrog Distribution. 
  • FileSpecA FileSpec resource specifies a File Spec, which provides the details of files to upload or download from Artifactory.
  • GitRepoA GitRepo is used to connect JFrog Pipelines to a source control repository. Adding it creates a webhook to the repo so that future commits will automatically create a new version with the webhook payload.
  • HelmChartThe HelmChart resource maps to a specific chart in an Artifactory Helm Repository. 
  • ImageAn Image resource is used to add a reference to a Docker image to your pipeline.
  • IncomingWebhookAn IncomingWebhook resource can trigger one or more jobs in your pipeline whenever the associated URL is called using the HTTP POST method. 
  • OutgoingWebhookAn OutgoingWebhook resource sends information by HTTP from a step to an external API endpoint through an Outgoing Webhook Integration.
  • PropertyBagA PropertyBag resource is used to pass information from one pipeline to another and to provide environment variables to a step in the format of a resource.
  • ReleaseBundleA ReleaseBundle resource specifies a set of artifacts in Artifactory that are distributed to Artifactory Edge nodes as a JFrog Distribution Release Bundle.
  • RemoteFileA RemoteFile resource enables using a file on a remote file server. 
  • VmClusterA VmCluster is used to represent a set of virtual machines.  It is predominantly used to deploy services/apps to the specified cluster(s) and in some cases it can also be used to run certain maintenance activities on the cluster(s) as a whole.

  • No labels
Copyright © 2020 JFrog Ltd.