Plug-in Documentation

Docker Registry

 

Overview

The Docker Registry source configuration plug-in automates importing of version artifacts from a Docker registry or the IBM Container Service. The plug-in detects Docker registry image tags and creates an associated component versions for the tag.

This plug-in includes one step:

Step palette

To access this plug-in in the palette, click Source and Repositories > Docker Import Tag.

Compatibility

This plug-in requires version 6.0 or later of IBM UrbanCode Deploy.

To use this plug-in with the IBM Containers service, you must install the Cloud Foundry cf command-line tool, and then log in from the command line using the cf login command. Download the cf command-line tool from the CLI and dev tools page on the IBM Bluemix website. To learn more about the cf command-line tool, see Cloud Foundry (cf) commands.

Installation

No special steps are required for installation. See Installing plug-ins in UrbanCode products.

History

Version 37

  • Fixes RFE 141571 – Added support for Docker trusted registry.

Version 36

  • APAR PH23367 – UNABLE TO USE PLUGIN WITH ARTIFACTORY : Resolved HttpClientUtils ambiguous api call dependency.

Version 34

  • Fixes APAR PH11785 Added pagination for Docker Registry type tags.

Version 33

  • Fixes APAR PH07152 Docker Registry source plugin incorrectly reports it cannot access the specified registry in some cases.

Version 32

  • Fixes APAR PI89045: add support for setting isFinished flag flag when importing versions.

Version 31

  • Fixes APAR PH00397 Docker Source Config plug-in fails if Artifactory reverse proxy does not return repositories.
  • Fixes APAR PI87707 a regression where the user who requested a manual version import was not being tracked.

Version 30

  • Fixes APAR PI94794 Unable to retrieve Docker image tags from IBM Cloud if using a proxy.

Version 23

  • Provides clearer messages when a version import fails.

Version 22

  • Fixes issue where images tags were not being imported if the Regular Expression for Tag Selection setting is left blank.

Version 21

  • Remove dependency on docker config.json file for IBM Cloud container registries.

Version 20

  • Updated to work with the latest IBM Cloud container registries.
  • Implements RFE 108578 to support regular expressions for importing docker images.
  • Updates Amazon ECR related tool tips.

Version 19

Updated to ensure all response texts are zOS compatible.

Version 18

  • Fixes issue where version imports fail if the registry doesnt support /v2 as the base URI entity.

Version 17

Added Amazon Web Services ECR support.

Version 16

Fixes APARs PI77450 and PI76826 Added support for Artifactory Docker registries.

Version 15

Removed unused Registry Email Address property.
Updated error output to better address errors at the time they occur.

Version 14

Support property file encryption.

Version 13

General quality of life improvements.

Version 12

Version 12 includes the following updates:

  • Removed OpenShift implementation. Please use the OpenShift Source plugin.

Version 11

Version 11 includes the following updates:

  • Updated OpenShift implementation to only use the CLI.

Version 10

Version 10 includes the following updates:

  • Resources are now correctly released after use.
  • Imports containing null Label values will continue smoothly.
  • Improved error output when image is not found.

Version 9

Version 9 includes the following features:

  • Updated ICS:
    • Bearer Token for authentication is correctly parsed
    • Space UID is properly specified
    • OS dynamic file sperators added
    • CF_HOME is now specifiable
    • CF_HOME defaults to user_home/.cf
  • Set VersionID output property to enable Run Process After Version Import functionality.

Version 8

Version 8 includes the following features:

  • You can now import OpenShift labels as version properties.
  • You can now use the CF_HOME environment variable and the cf login tool when you import from the IBM Containers service.

Version 5

Version 5 includes a fix for APAR PI57417. The plug-in now checks the agent settings for acceptance of self-signed certificates.

Version 4

Version 4 supports the IBM Containers service.

Usage

Nexus container registry

The Docker Registry source configuration plug-in supports Nexus as a container registry when selecting the Docker Registry Type.

For information on using Nexus as a container registry, see the Secure Docker Registries for Repository Manager 3 guide from Sonatype.

Properties

The following properties must be specified to configure an Nexus hosted Docker registry.

  • Image Name: The namespace or repository of the image in the Docker registry.
  • Registry: The host name of the Nexus server or the reverse proxy of the Docker registry.
  • Registry Type: Select the Nexus option.
  • Registry Username: If the Docker registry is secure, specify a user name to authenticate.
  • Registry Password: If the Docker registry is secure, specify the password associated with the user name to authenticate.

Amazon EC2 Container Registry

UrbanCode Deploy can be used to import Docker images from an Amazon EC2 Container Registry (ECR) using the Docker Registry source configuration plug-in. Before using this plug-in to create or import versions from Amazon ECR, Docker and AWS CLI must be installed on the UrbanCode Deploy agent used for version imports. See the Docker and Amazon ECS documentation for details about how to install these requirements.

Properties

The following properties are used when connecting to Amazon Elastic Container Service (ECS).

    • Image Name: Use an Elastic Container Registry (ECR) repositoryName without namespace as the image name. To see the list of available repositories, run the command: Aws ecr describe-repositories
    • Regular Expression for Tag Selection: Optional. Provide regular expression to select tags to create component versions for.
    • Registry: The URL of the Amazon registry to connect to.
    • Registry Type: Select the Amazon ECR option.
    • Registry Username: The user name used to login to the Docker registry. For the Amazon ECR, use an access key.
    • Registry Password: The password used to login to the Docker registry. For Amazon ECR, use a secret key.
    • Registry API Key: Not used with Amazon ECS
    • Allow Insecure Registry Connection: default is false. Select this option to allow insecure connections to the Docker registry.
    • Naming Convention: The naming convention for component versions. The three options are Tag id, Tag id, and Tag. Docker tags can be changed. If component versions need to be immutable, select a naming convention that includes the ID.

 

    • AWS Region: The region to use when importing images from Amazon ECR.
    • AWS Command Line File: the complete path of the AWS command line runtime file. The default is aws.

 

 

Sample Configuration

 

IBM Container Registry

Support for the latest IBM Cloud container registries was changed in version 20 of the Docker Registry plug-in to remove dependencies on the IBM Cloud (Bluemix) Cloud Foundry plug-in and the depreciated Bluemix IBM Containers plug-in (bx ic). Support for OAuth protected IBM Cloud container registries was also introduced in version 20.

The IBM Cloud (Bluemix) command line interface, the IBM Cloud container registry plug-in, and IBM Cloud container service plug-in are required to be installed on your UrbanCode Deploy agent machine to access IBM Cloud container registries. Docker itself must also be installed on the agent machine.

Properties

The following properties are used when connecting to an IBM Cloud container registry.

  • Image Name: The name of the image in the format [namespace/][repository].
  • Registry: The name of registry to connect to (for example, registry.ng.bluemix.net).
  • Registry Type: Select the IBM Containers option.
  • IBM Cloud API Endpoint: The IBM Cloud API endpoint to use (for example, api.ng.bluemix.net)
  • IBM Cloud Space: The space to use when connected to IBM Cloud.
  • IBM Cloud Organization: The organization to use when connected to IBM Cloud.
  • Bluemix Home: Specify the location of your Bluemix config.json file
  • Registry Username: The username to use when connecting to IBM Cloud. Specified if not using an API key to connect.
  • Registry Password: The password to use when connecting to IBM Cloud. Specified if not using an API key to connect.
  • Registry API Key: The API key to use when connecting to IBM Cloud. Specified if not using a username/password to connect.

Sample Configuration

Image and Registry Properties

Running the bx cr images command will return something like this:

In the example above, the REPOSITORY column shows a name made of three pieces. Take registry.ng.bluemix.net/mynamespace2/bgdemohello as an example. The text registry.ng.bluemix.net refers to the container registry. The text mynamespace2 refers to a namespace which is used for personal or private images for a specific organization or user. The text bgdemohello refers to the image name itself.

Following our example, in UrbanCode Deploy, the Image Name field would contain the value mynamespace2/bgdemohello and the Registry filed would contain registry.ng.bluemix.net.

The Registry Type field should be set to IBM Containers, as that instructs the plug-in to connect to an IBM Cloud container registry.

IBM Cloud Properties

There are several properties used when connecting to IBM Cloud (Bluemix). The IBM Cloud API Endpoint, IBM Cloud Space, and IBM Cloud Organization field may be set to values used when connecting to IBM Cloud. For authentication, the Registry Username and Registry Password fields may be filled out, or users may specify an API key using the Registry API Key field.

Bluemix Home

The location of your Bluemix config.json file is needed to pull image tags from the IBM Cloud container registry. After connecting to Bluemix, an IAMRefreshToken is placed in the Bluemix config.json file. This token is required when the Docker registry UrbanCode Deploy plug-in makes a REST call to pull image tags from the container registry.

Basic Workflow

Below is the general approach the Docker Registry plug-in takes when connecting to an IBM Cloud container registry:

  1. Run a command line command to connect to IBM Cloud (Bluemix)
  2. Run a command line command to log into the container registry
  3. Make a REST call to the container registry to pull image tags using a token found in the Bluemix config.json file
  4. If the REST call returns 401-Unauthroized, OAuth may be enabled. Request an OAuth token via a REST call, then make a REST call to pull images using the OAuth token.

Artifactory Configuration

UrbanCode Deploy began supporting Artifactory hosted Docker registries starting with version 16 of the Docker Registry plug-in.

Properties

The following properties must be specified to configure an Artifactory hosted Docker registry.

  • Image Name: The namespace or repository of the image in the Docker registry.
  • Registry: The host name of the Artifactory server or the reverse proxy of the Docker registry.
  • Registry Type: Select the Artifactory option.
  • Registry Username: If the Docker registry is secure, specify a user name to authenticate.
  • Registry Password: If the Docker registry is secure, specify the password associated with the user name to authenticate.

Sample Configuration

Image Name

Specify the complete repository path to the Docker registry. Do not specify a version. The source configuration identifies all image versions and create new component versions for each. If you were importing the below sample repository, you would specify central-it-docbuild-docker/docbuild-dcs-buildenv as the Image Name. Following version import, there will be 2 new component versions: 1.1 and latest. If the _uploads folder had other docker images for import, the Image Name would be central-it-docbuild-docker/docbuild-dcs-buildenv/_uploads. A new component should be made for the each registry. Its important to recognize that the first string separated by the back slash is considered the namespace (central-it-docbuild-docker) while everything following is the repository (docbuild-dcs-buildenv/_uploads).

Registry

The plug-in supports two Artifactory Docker Registry scenarios:

  • Artifactory servers hostname
  • Reverse proxy to the Docker registry

On import, the plugin will ping the server and determine which type of URL is specified. While this process is taken care of within the plug-in, its important to understand that the REST calls paths vary slightly. The reverse proxy provides direct access to a specific Docker Registry namespace. For example, if we pretend that from the above example my-artifactory-server.com:8443 is the Artifactorys hostname, the plug-in connects to the registry using the following constructed URL: https://my-artifactory-server.com:8443/artifactoy/api/docker/central-it-docbuild-docker. However, one could specify a reverse proxy that would route all calls to that URL and therefore, simplify REST calls and mirror Dockers supported API. While a small point that is resolved by the plug-in, it is important to understand the difference in case debugging is required. Further information and directions on setting up your own reverse proxy can be found on Artifactorys documentation page.

Other Properties

The Registry Type property must be set to Artifactory otherwise a different Docker connection method is used. The incorrect specification results in an immediate failure. The user name and password properties are required, if your Docker registry is secured.

General Source Config Specification

To create a component by importing from Docker, complete the following steps. For more information, see Creating components in the product help.

  1. On the Components page in IBM UrbanCode Deploy, click Create New Component.
  2. In the Source Config Type list, select Docker.
  3. Provide all of the necessary information, such as the Image Name.
  4. Click Save.
  5. Click the Versions tab for the component.
  6. Click Import New Versions.

Settings

Process steps in the Docker plug-in

Import Version

Creates a new component version for a tag

This step has no input properties.

Roles in the Docker plug-in

DockerTagImport

Properties for the DockerTagImport role
Name Type Description
AWS Command Line File String Complete path of the AWS command line runtime file. Default: aws
AWS Region String Region to use when importing images from Amazon ECR.
Allow Insecure Registry Connection Boolean Select this option to allow insecure connections to the Docker registry
Bluemix Home String For use with IBM Clouds container registry. Specify the directory containing your
Bluemix config.json file (for example, /root/.bluemix)
IBM Cloud API Endpoint String For example, https://api.ng.bluemix.net.
IBM Cloud Organization String For use with IBM Clouds container registry. The organization to log into.
If left blank, the api will not be reset.
IBM Cloud Space String For use with IBM Clouds container registry. The space to log into. If
left blank, the space will not be reset.
Image Name String The [namespace/]repository of the image in the Docker registry. For Amazon, namespace
not needed.
Naming Convention Enumeration: The naming convention for component versions. Docker tags can be changed. If component
versions need to be immutable, select a naming convention that includes the ID.
Registry String If image is host:5000/namespace/repository:tag use host:5000. Leave blank for Docker
Hub. If Artifactory, supply the servers hostname or reverse proxy.
Registry API Key Password API key to be used when logging in to the registry. May be a string or location of
a key file. Use in place of a username and password.
Registry Password Password The password used to login to the Docker registry. Default value is ${p?:dockerPassword}.
For Amazon ECR, use secret key
Registry Type Enumeration: Specify which API to connect with the Docker Registry. When using IBM Containers,
provide IBM Cloud Credentials. For Amazon ECR, use AWS access
key as username and secret key as password
Registry Username String The username used to login to the Docker registry. For Amazon ECR, use access key
Regular Expression for Tag Selection String Provide regular expression to select tags to create component versions for.