As a Code Stream administrator or developer, you can use the Docker trigger in Code Stream cloud services. 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

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. If the Docker registry endpoint is on-premises, select the cloud proxy. If the endpoint is cloud-based, keep the setting as Default.
    7. Select the server type as DockerHub.
    8. Enter the URL to the Docker Hub repository.
    9. 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. Sign in to vRealize Automation Cloud.
      2. Click the drop-down arrow by your name.
      3. Click My Account.
      4. Click API Tokens.
      5. Click Generate Token.
        1. Enter a Token Name.
        2. Under Organization Roles, select Organization Owner.
        3. Under Service Roles, click to expand VMware Code Stream and select Code Stream Administrator.
        4. Click Generate.

          The Token Generated window displays a token with the name that you specified and the name of your organization.

      6. Click the COPY icon.

        Clicking COPY ensures that you capture the exact string and is more reliable than using your pointer to copy the string.

    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.