Docker Registry

Configure Spinnaker to use Docker as a source for images.

: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:

  1. 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:

  1. 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:

  1. USERNAME=yourusername
  2. 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 .

    1. 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/objectViewer 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.)

    1. SERVICE_ACCOUNT_NAME=spinnaker-gcr-account
    2. SERVICE_ACCOUNT_DEST=~/.gcp/gcr-account.json
    4. gcloud iam service-accounts create \
    5.     $SERVICE_ACCOUNT_NAME \
    6.     --display-name $SERVICE_ACCOUNT_NAME
    8. SA_EMAIL=$(gcloud iam service-accounts list \
    9.     --filter="displayName:$SERVICE_ACCOUNT_NAME" \
    10.     --format='value(email)')
    12. PROJECT=$(gcloud config get-value project)
    14. gcloud projects add-iam-policy-binding $PROJECT \
    15.     --member serviceAccount:$SA_EMAIL \
    16.     --role roles/browser
    18. gcloud projects add-iam-policy-binding $PROJECT \
    19.     --member serviceAccount:$SA_EMAIL \
    20.     --role roles/objectViewer
    22. mkdir -p $(dirname $SERVICE_ACCOUNT_DEST)
    24. gcloud iam service-accounts keys create $SERVICE_ACCOUNT_DEST \
    25.     --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 :

    1. PASSWORD_FILE=$SERVICE_ACCOUNT_DEST

  4. Enable the provider.

    1. 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.

    1. hal config provider docker-registry account add my-docker-registry \
    2.  --address $ADDRESS \
    3.  --username _json_key \
    4.  --password-file $PASSWORD_FILE

Amazon Elastic Container Registry (ECR)

  1. Set the registry address.

    ECR registry addresses are specific to an AWS account and region. You can retrieve the address from the ECR console, or with aws ecr describe-repositories.

    1. ADDRESS=012345678910.dkr.ecr.us-east-1.amazonaws.com
    2. REGION=us-east-1

  2. Enable the provider.

    1. hal config provider docker-registry enable

  3. Set up authentication.

    Because the Docker Registry API does not support the standard AWS authentication methods, the Halyard --password-command option will be configured to use the AWS CLI to retrieve an ECR authentication token on a regular interval with IAM credentials on the Spinnaker instance. The ECR API returns the authentication token as a base64 encoded string comprised of the username and password, which the password command will decode and retrieve the password from the payload.

    Ensure that the AWS CLI is installed on the Spinnaker instance running the Clouddriver service. For example:

    1. apt install python3-pip
    2. pip3 install awscli

    The Spinnaker instance running the Clouddriver service will also need permissions to interact with the ECR repository. Attach the AmazonEC2ContainerRegistryReadOnly managed policy to the IAM role for your Spinnaker instance profile or (if IAM user credentials are saved in ~/.aws) your Spinnaker IAM user. For example,

    1. aws iam attach-role-policy --policy-arn arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly --role-name SpinnakerInstanceRole

    or:

    1. aws iam attach-user-policy --policy-arn arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly --user-name spinnaker

  4. Add the account.

    1. hal config provider docker-registry account add my-ecr-registry \
    2.  --address $ADDRESS \
    3.  --username AWS \
    4.  --password-command "aws --region $REGION ecr get-authorization-token --output text --query 'authorizationData[].authorizationToken' | base64 -d | sed 's/^AWS://'"

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 <code>/_catalog</code> 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.

RegistryFQDNCatalog
GCRgcr.io, eu.gcr.io, us.gcr.io, asia.gcr.io, b.gcr.ioYes
DockerHubindex.docker.ioNo
Quayquay.ioYes
ECRaccount-id.dkr.ecr.region.amazon.aws.comYes
JFrog Artifactoryserver-repo.jfrog.io?

Add the account

First, make sure that the provider is enabled:

  1. 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:

  1. hal config provider docker-registry account add my-docker-registry \
  2.     --address $ADDRESS \
  3.     --repositories $REPOSITORIES \
  4.     --username $USERNAME \
  5.     --password # Do not supply your password as a flag, you will be prompted for your
  6.                # 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.

Last modified May 7, 2021: docs(migration): fix imgs and links (9a18ce6)