How to Manually Run a Check Step Using a Concourse Resource Container Image

Products

• Concourse for VMware Tanzu

Issue/Introduction

All Concourse resources run from within an OCI compliant container image. In some circumstances it may be helpful to run these images separately to isolate possible issues outside of the Concourse deployment. The intent of this article is to provide guidance on this process.

Please Notes: The process outlined in this document requires a Docker container runtime environment.

Environment

Product Version: 7.9

Resolution

1. Locate the Resource to be Tested
Most resource container images are available on Dockerhub. This includes all of the base resource images that are shipped with Concourse which can be located under the Concourse project page. We will be using the registry-image-resource container in our examples

In order to determine the resource type that will be tested, you will need to examine the definition of the resource within the pipeline configuration.For example, consider the following resource definition:

resources:
- name: pivnet-image
  type: registry-image
  source:
    repository: internalrepo.example.com/cache/pivotalcf/pivnet-resource
    tag: latest-final

The above shows the definition for a resource named pivnet-image of type registry-image. This resource will use the registry-image-resource container image packaged with Concourse to retrieve the pivnet-resource image from the pivotalcf project via a repository cache located at internalrepo.example.com/cache.

If there were issues with this resource being used from the internal cache or if the resource was failing to be retrieved, one way to test this would be to manually retrieve the registry-image-resource image and run it elsewhere so that the exact same operations could be performed against the same repository only outside of the Concourse deployment.

2. Retrieve the Image
Once the desired resource image has been retrieved, we would want to pull the image into our container runtime environment:

docker pull concourse/registry-image-resource:latest

Please note that the :latest tag should be replaced with the tag that most closely matches the version of the resource being tested.

3. Convert the Resource Configuration to JSON

Concourse resource operations receive their inputs in JSON format via standard input. In order to perform this test, we will need to translate the source section of the resource definition into JSON. Using the above resource definition as an example, this would be the corresponding JSON formatted configuration:

{
    "source": {
        "repository": "internalrepo.example.com/cache/pivotalcf/pivnet-resource",
        "tag" : "latest-final"
    }
}

Things to note:

• Only the source section of the resource definition is required
• All fields translate directly from YAML to JSON

4. Run a Container Using the Resource Image
At this stage we will need to initialize a container running on the desired resource image with a shell so that we can manually perform the resource check operation. Using the image pulled from the previous command as an example:

docker run -it concourse/registry-image-resource:latest /bin/bash

This will result in a simple Bash prompt.

5. Stage the Resource JSON in a File
Create a file inside the running container with the JSON resource source information. For our example, the file will be named rsource.json.

6. Run the Resource Operation Using the Source Configuration
As previously mentioned, all resource operations accept the JSON formatted source configuration via standard input. All resource scripts are stored in /opt/resource. To run the check step from within this container, run the following:

cat resource.json | /opt/resource/check

Output will differ depending on the resource type being used. In our example, we can expect just the tag and the digest of the registry image being checked:

[{"tag":"latest-final","digest":"sha256:93062ea4eb237a1f13c20285c1580644f3ee756118731eb258a8d10dccc828f6"}]

For additional information please see the Implementing a Resource Type  section of the Concourse CI documentation.