As a Code Stream administrator or developer, you can use the Docker trigger in Code Stream. The Docker trigger runs a standalone continuous delivery (CD) pipeline whenever a build artifact is created or updated. The Docker trigger runs your CD pipeline, which pushes the new or updated artifact as a container image to a Docker Hub repository. The CD pipeline can run as part of your automated builds.

For example, to continuously deploy your updated container image through your CD pipeline, use the Docker trigger. When your container image gets checked into the Docker registry, the webhook in Docker Hub notifies Code Stream that the image changed. This notification triggers the CD pipeline to run with the updated container image, and upload the image to the Docker Hub repository.

To use the Docker trigger, you perform several steps in Code Stream.

Table 1. How to use the Docker trigger
What you do... More information about this action...

Create a Docker registry endpoint.

For Code Stream to trigger your pipeline, you must have a Docker Registry endpoint. If the endpoint does not exist, you can select an option that creates it when you add the webhook for the Docker trigger.

The Docker registry endpoint includes the URL to the Docker Hub repository.

Add input parameters to the pipeline that auto inject Docker parameters when the pipeline runs.

You can inject Docker parameters into the pipeline. Parameters can include the Docker event owner name, image, repository name, repository namespace, and tag.

In your CD pipeline, you include input parameters that the Docker webhook passes to the pipeline before the pipeline triggers.

Create a Docker webhook.

When you create the Docker webhook in Code Stream, it also creates a corresponding webhook in Docker Hub. The Docker webhook in Code Stream connects to Docker Hub through the URL that you include in the webhook.

The webhooks communicate with each other, and trigger the pipeline when an artifact is created or updated in Docker Hub.

If you update or delete the Docker webhook in Code Stream, the webhook in Docker Hub is also updated or deleted.

Add and configure a Kubernetes task in your pipeline.

When an artifact is created or updated in the Docker Hub repository, the pipeline triggers. Then, it deploys the artifact through the pipeline to the Docker host in your Kubernetes cluster.

Include a local YAML definition in the task.

The YAML definition that you apply to the deployment task includes the Docker container image. If you need to download an image from a privately-owned repository, the YAML file must include a section with the Docker config Secret. See the CD portion of Planning a CICD native build in Code Stream before using the smart pipeline template

When an artifact is created or updated in the Docker Hub repository, the webhook in Docker Hub notifies the webhook in Code Stream, which triggers the pipeline. The following actions occur:

  1. Docker Hub sends a POST request to the URL in the webhook.
  2. Code Stream runs the Docker trigger.
  3. The Docker trigger starts your CD pipeline.
  4. The CD pipeline pushes the artifact to the Docker Hub repository.
  5. Code Stream triggers its Docker webhook, which runs a CD pipeline that deploys the artifact to your Docker host.

In this example, you create a Docker endpoint and a Docker webhook in Code Stream that deploys your application to your development Kubernetes cluster. The steps include the example code for the payload that Docker posts to the URL in the webhook, the API code that it uses, and the authentication code with the secure token.

Prerequisites

  • Verify that a continuous delivery (CD) pipeline exists in your Code Stream instance. Also verify that it includes one or more Kubernetes tasks that deploy your application. See Planning to natively build, integrate, and deliver your code in Code Stream.
  • Verify that you can access an existing Kubernetes cluster where your CD pipeline can deploy your application for development.
  • Verify that you are a member of a project in Code Stream. If you are not, ask a Code Stream administrator to add you as a member of a project. See How do I add a project in Code Stream.

Procedure

  1. Create a Docker registry endpoint.
    1. Click Endpoints.
    2. Click New Endpoint.
    3. Start typing name of existing project.
    4. Select the type as Docker Registry.
    5. Enter a relevant name.
    6. Select the server type as DockerHub.
    7. Enter the URL to the Docker Hub repository.
    8. Enter the name and password that can access the repository.
    When you add a Docker Registry endpoint, it is important that you accept the certificate because the endpoint can require it.
  2. In your CD pipeline, set the input properties to auto inject Docker parameters when the pipeline runs.
    When you add input parameters to a pipeline, you click the Input tab and select the type of parameters, such as Gerrit, Git, or Docker.
  3. Create a Docker webhook.
    1. Click Triggers > Docker.
    2. Click New Webhook for Docker.
    3. Select a project.
    4. Enter a relevant name.
    5. Select your Docker registry endpoint.
      If the endpoint does not yet exist, click Create Endpoint and create it.
    6. Select the pipeline with Docker injected parameters for the webhook to trigger. See Step 2.
      If the pipeline was configured with custom added input parameters, the Input Parameters list displays parameters and values. You can enter values for input parameters that will be passed to the pipeline with the trigger event. Or you can leave the values blank, or use the default values if defined.

      For more information about parameters on the input tab, see Planning a CICD native build in Code Stream before manually adding tasks.

    7. Enter the API Token.
      The CSP API token authenticates you for external API connections with Code Stream. To obtain the API token:
      1. Click Generate Token.
      2. Enter the email address associated with your user name and password and click Generate.
        The token that you generate is valid for six months. It is also known as a refresh token.
        • To keep the token as a variable for future use, click Create Variable, enter a name for the variable and click Save.
        • To keep the token as a text value for future use, click Copy and paste the token into a text file to save locally.
        You can choose to both create a variable and store the token in a text file for future use.
      3. Click Close.
    8. Enter the build image.
    9. Enter a tag.
      When you create a webhook for the Docker trigger, you must provide an API token that authenticates you for external API connections with Code Stream.
    10. Click Save.
      The webhook card appears with the Docker webhook enabled. If you want to make a dummy push to the Docker Hub repository without triggering the Docker webhook and running a pipeline, click Disable.
  4. In your CD pipeline, configure your Kubernetes deployment task.
    1. In the Kubernetes task properties, select your development Kubernetes cluster.
    2. Select the Create action.
    3. Select the Local Definition for the payload source.
    4. Then select your local YAML file.
      For example, Docker Hub might post this local YAML definition as the payload to the URL in the webhook: 
      {
"callback_url": "https://registry.hub.docker.com/u/svendowideit/testhook/hook/2141b5bi5i5b02bec211i4eeih0242eg11000a/",
"push_data": {
"images": [
"27d47432a69bca5f2700e4dff7de0388ed65f9d3fb1ec645e2bc24c223dc1cc3",
"51a9c7c1f8bb2fa19bcd09789a34e63f35abb80044bc10196e304f6634cc582c",
"..."
],
"pushed_at": 1.417566161e+09,
"pusher": "trustedbuilder",
"tag": "latest"
},
"repository": {
"comment_count": 0,
"date_created": 1.417494799e+09,
"description": "",
"dockerfile": "#\n# BUILD\u0009\u0009docker build -t svendowideit/apt-cacher .\n# RUN\u0009\u0009docker run -d -p 3142:3142 -name apt-cacher-run apt-cacher\n#\n# and then you can run containers with:\n# \u0009\u0009docker run -t -i -rm -e http_proxy http://192.168.1.2:3142/ debian bash\n#\nFROM\u0009\u0009ubuntu\n\n\nVOLUME\u0009\u0009[\/var/cache/apt-cacher-ng\]\nRUN\u0009\u0009apt-get update ; apt-get install -yq apt-cacher-ng\n\nEXPOSE \u0009\u00093142\nCMD\u0009\u0009chmod 777 /var/cache/apt-cacher-ng ; /etc/init.d/apt-cacher-ng start ; tail -f /var/log/apt-cacher-ng/*\n",
"full_description": "Docker Hub based automated build from a GitHub repo",
"is_official": false,
"is_private": true,
"is_trusted": true,
"name": "testhook",
"namespace": "svendowideit",
"owner": "svendowideit",
"repo_name": "svendowideit/testhook",
"repo_url": "https://registry.hub.docker.com/u/svendowideit/testhook/",
"star_count": 0,
"status": "Active"
}
}
      The API that creates the webhook in Docker Hub uses this form: https://cloud.docker.com/v2/repositories/%3CUSERNAME%3E/%3CREPOSITORY%3E/webhook_pipeline/
      The JSON code body resembles: 
      {
"name": "demo_webhook",
"webhooks": [
{
"name": "demo_webhook",
"hook_url": "http://www.google.com"
}
]
}
      To receive events from the Docker Hub server, the authentication scheme for the Docker webhook that you create in Code Stream uses an allowlist authentication mechanism with a random string token for the webhook. It filters events based on the secure token, which you can append to hook_url.
      Code Stream can verify any request from the Docker Hub server by using the configured secure token. For example: hook_url = IP:Port/pipelines/api/docker-hub-webhooks?secureToken = ""
  5. Create a Docker artifact in your Docker Hub repository. Or, update an existing artifact.
  6. To confirm that the trigger occurred, and see the activity on the Docker webhook, click Triggers > Docker > Activity.
    You can observe the Docker webhook commit times, images, tags, and more on the Docker Activity tab.
  7. Click Executions, and observe your pipeline as it runs.
    As the pipeline runs, it displays the status RUNNING, and the stage icons display the progress.
  8. Click the running stage and view the tasks as the pipeline runs.
    When you click one of the stage icons, you can observe the status of each task in the stage as the pipeline runs.

Results

Congratulations! You set up the Docker trigger to run your CD pipeline continuously. Your pipeline can now upload new and updated Docker artifacts to the Docker Hub repository.

What to do next

Verify that your new or updated artifact is deployed to the Docker host in your development Kubernetes cluster.