Docker Registry

:warning: This only acts as a source of images, and does not include support for deploying Docker images.

When configuring Docker Registries, an Account maps to a credential able to authenticate against a certain set of Docker repositories.

Perform the steps in this article in the same place where you have Halyard installed, whether in a Docker container or locally on Ubuntu/Debian or macOS.

Prerequisites

  • The Docker Registry you are configuring must already exist.
  • That Registry must support the v2 registry API.
  • If the Registry doesn’t have at least 1 tag among the repositories you define in your Account, Halyard throws a warning.

Registry providers

You can set up a Docker Registry provider for Spinnaker using any of the repositories listed here. Each one supports the same API, but there are subtle differences in how to get them to work with Spinnaker.

DockerHub

The DockerHub registry address is index.docker.io, keep track of this for later:

ADDRESS=index.docker.io

Dockerhub hosts a mix of public and private repositories, but does not expose a catalog endpoint to programmatically list them. Therefore you need to explicitly list which Docker repositories you want to index and deploy. For example, if you wanted to deploy the public NGINX image, alongside your private app image, your list of repositories would look like:

REPOSITORIES=library/nginx yourusername/app

NOTE: Keep in mind that the repository name is typically either prefixed with library/ for most public images, or <username>/ for images belonging to user <username>/.

If any of your images aren’t publicly available, make sure you know your DockerHub username & password to supply to hal later:

USERNAME=yourusername
PASSWORD=hunter2

Google Container Registry

  1. Set the registry address.

    There are a few different registry addresses for GCR, depending on where you want to store your images. The most likely address is gcr.io, but there are more options available.

    ADDRESS=gcr.io
    
  2. (Optional) Enable the Resource Manager API.

    Enable this API if you want to use the catalog endpoint to programatically list all images available to your credentials, so you don’t have supply repositories manually.

  3. Set up authentication.

    A service account is the preferred way to authenticate to GCR. Use the commands below to create and download a service account to be used as your password with the required roles/storage.admin role, assuming the registry exists in your current gcloud project.

    (You can use an access token instead, but that’s problematic for Spinnaker because the token is short lived, and you are responsible for refreshing it.)

    SERVICE_ACCOUNT_NAME=spinnaker-gcr-account
    SERVICE_ACCOUNT_DEST=~/.gcp/gcr-account.json
    
    gcloud iam service-accounts create \
        $SERVICE_ACCOUNT_NAME \
        --display-name $SERVICE_ACCOUNT_NAME
    
    SA_EMAIL=$(gcloud iam service-accounts list \
        --filter="displayName:$SERVICE_ACCOUNT_NAME" \
        --format='value(email)')
    
    PROJECT=$(gcloud info --format='value(config.project)')
    
    gcloud projects add-iam-policy-binding $PROJECT \
        --member serviceAccount:$SA_EMAIL \
        --role roles/browser
    
    gcloud projects add-iam-policy-binding $PROJECT \
        --member serviceAccount:$SA_EMAIL \
        --role roles/storage.admin
    
    mkdir -p $(dirname $SERVICE_ACCOUNT_DEST)
    
    gcloud iam service-accounts keys create $SERVICE_ACCOUNT_DEST \
        --iam-account $SA_EMAIL
    

    Your GCR password is now in a file called $SERVICE_ACCOUNT_DEST. For Spinnaker to authenticate against GCR, keep track of these environment vars to be passed to hal later:

    # this is always the username for this authentication format
    USERNAME=_json_key
    PASSWORD_FILE=$SERVICE_ACCOUNT_DEST
    
  4. Enable the provider.

    hal config provider docker-registry enable
    
  5. Add the account.

    Note: if you’re running Halyard in a Docker container, you might have to restart the container, now mounting the ~/.gcp directory.

    hal config provider docker-registry account add my-docker-registry \
     --address $ADDRESS \
     --username $USERNAME \
     --password-file $PASSWORD_FILE
    
    

Other registries

Most registries fit either the Dockerhub or GCR pattern described above, or some mix of the two. In all cases you need to know the FQDN of the registry, and your username/password pair if you are accessing private images. If your registry supports the /_catalog endpoint you do not have to list your repositories. If it does not, keep in mind that the repository names are generally of the form <username>/<image name>. Halyard verifies this for you.

Registry FQDN Catalog
GCR gcr.io, eu.gcr.io, us.gcr.io, asia.gcr.io, b.gcr.io Yes
DockerHub index.docker.io No
Quay quay.io Yes
ECR account-id.dkr.ecr.region.amazon.aws.com ?
JFrog Artifactory server-repo.jfrog.io ?

Add the account

First, make sure that the provider is enabled:

hal config provider docker-registry enable

Assuming that your registry has address $ADDRESS, with repositories $REPOSITORIES, username $USERNAME, and password $PASSWORD, run the following hal command to add an account named my-docker-registry to your list of Docker Registry accounts:

hal config provider docker-registry account add my-docker-registry \
    --address $ADDRESS \
    --repositories $REPOSITORIES \
    --username $USERNAME \
    --password # Do not supply your password as a flag, you will be prompted for your
               # password on STDIN

Advanced Account Settings

If you are looking for more configurability, please see the other options listed in the Halyard Reference.

Next Steps

Optionally, you can set up another cloud provider, but otherwise you’re ready to choose an environment in which to install Spinnaker.