How do I use the Docker trigger in Automation Pipelines to run a continuous delivery pipeline

As a Automation Pipelines administrator or developer, you can use the Docker trigger in Automation Pipelines 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 Automation Pipelines 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 Automation Pipelines.

Table 1. How to use the Docker trigger

What you do...	More information about this action...
Create a Docker registry endpoint.	For Automation Pipelines 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 Automation Pipelines, it also creates a corresponding webhook in Docker Hub. The Docker webhook in Automation Pipelines 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 Automation Pipelines, 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 Automation Pipelines 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 Automation Pipelines, which triggers the pipeline. The following actions occur:

1. Docker Hub sends a POST request to the URL in the webhook.
2. Automation Pipelines 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. Automation Pipelines 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 Automation Pipelines 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 Automation Pipelines 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 Automation Pipelines.
• 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 Automation Pipelines. If you are not, ask a Automation Pipelines administrator to add you as a member of a project. See How do I add a project in Automation Pipelines.
• If your Docker Hub repository is an on-premises endpoint, create a cloud proxy so that Automation Pipelines can communicate with it. For an example, see Setting up Automation Pipelines to model my release process.

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.
   
2. In your CD pipeline, set the input properties to auto inject Docker parameters when the pipeline runs.
   
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 How you'll create the CICD pipeline and configure the workspace.

   7. Enter the API Token.
      The VMware Cloud Services API token authenticates you for external API connections with Automation Pipelines. To obtain the API token:

      1. Sign in to VMware Aria Automation.
      2. Sign in to
      3. Click the drop-down arrow by your name.
      4. Click My Account.
      5. Click API Tokens.
      6. Click Generate a New API Token.
         1. Enter a Token Name.
         2. Under Organization Roles, click to expand All Organization Roles and select Organization Owner.
         3. Under Service Roles, click to expand VMware Aria Automation > Pipelines and select Pipelines Administrator.
         4. Click Generate.

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

      7. 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.
      
   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 Automation Pipelines 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.
      Automation Pipelines 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.
   
7. Click Executions, and observe your pipeline as it runs.
   
8. Click the running stage and view the tasks 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.