Configure machines for Quay Enterprise

Quay Enterprise allows you to create user accounts and teams, or groups, of those users that mirror your existing org chart. A special type of user, a robot account, is designed to be used programatically by deployment systems and other pieces of software. Robot accounts are usually configured with read-only access to a repository.

This guide we will assume you have the DNS record registry.example.com configured to point to your Quay Enterprise installation.

Credentials

Each Container Linux machine needs to be configured with the username and password for a robot account in order to deploy your containers. Docker looks for configured credentials in a .dockercfg file located within the user's home directory. You can download this file directly from the Quay Enterprise interface. Let's assume you've created a robot account called myapp+deployment.

Writing the .dockercfg can be specified in a Container Linux Config with the files parameter, or created manually on each machine.

Kubernetes pull secret

If you are using Quay Enterprise in conjunction with a Kubernetes or Tectonic cluster, it's easiest to use the built-in secret distribution method. This method allows for you to use different sets of robot accounts on a per-app basis, and also allows for them to be updated or rotated at any time across all machines in the cluster.

An "Image Pull Secret" is a special secret that Kubernetes will use when pulling down the containers in a pod. It is a base64-encoded Docker config file. Here's an example:

$ cat ~/.dockercfg | base64
eyAiaHR0cHM6Ly9pbmRleC5kb2NrZXIuaW8vdjEvIjogeyAiYXV0aCI6ICJabUZyWlhCaGMzTjNiM0prTVRJSyIsICJlbWFpbCI6ICJqZG9lQGV4YW1wbGUuY29tIiB9IH0K
apiVersion: v1
kind: Secret
metadata:
  name: myappcreds
data:
  .dockercfg: eyAiaHR0cHM6Ly9pbmRleC5kb2NrZXIuaW8vdjEvIjogeyAiYXV0aCI6ICJabUZyWlhCaGMzTjNiM0prTVRJSyIsICJlbWFpbCI6ICJqZG9lQGV4YW1wbGUuY29tIiB9IH0K
type: kubernetes.io/dockercfg

To use this secret, first submit it into the cluster:

$ kubectl create -f /tmp/myappcreds.yaml
secrets/myappcreds

Reference pull secret with RC

Reference your new secret in a Replication Controller YAML definition:

apiVersion: v1
kind: ReplicationController
metadata:
  name: myapp
spec:
  replicas: 1
  selector:
    tier: webapp
  template:
    metadata:
      labels:
        tier: webapp
    spec:
      containers:
        - name: foo
          image: quay.io/coreos/etcd:v2.2.1
          ports:
            - containerPort: 2380
      imagePullSecrets:
        - name: myappcreds

Assign a default pull secret per namespace

To use a specific pull secret as the default in a specific namespace, you can create a Service Account that will be available to each pod. This is new in Kubernetes v1.1.

Container Linux Config

A snippet to configure the credentials via files in a Container Linux Config looks like:

This is the human-readable config file. This should not be immediately passed to Container Linux. Learn more.
# This config is meant to be consumed by the config transpiler, which will
# generate the corresponding Ignition config. Do not pass this config directly
# to instances of Container Linux.

storage:
  files:
    - path: /root/.dockercfg
      filesystem: root
      mode: 0644
      contents:
        inline: |
          {
           "https://registry.example.com/v1/": {
            "auth": "cm9ic3p1bXNrajYzUFFXSU9HSkhMUEdNMEISt0ZXN0OkdOWEVHWDRaSFhNUVVSMkI1WE9MM1k1S1R1VET0I1RUZWSVg3TFRJV1I3TFhPMUI=",
            "email": ""
           }
          }
This is the raw machine configuration, which is not intended for editing. Learn more. Validate the config here.
{
  "ignition": {
    "version": "2.0.0",
    "config": {}
  },
  "storage": {
    "files": [
      {
        "filesystem": "root",
        "path": "/root/.dockercfg",
        "contents": {
          "source": "data:,%7B%0A%20%22https%3A%2F%2Fregistry.example.com%2Fv1%2F%22%3A%20%7B%0A%20%20%22auth%22%3A%20%22cm9ic3p1bXNrajYzUFFXSU9HSkhMUEdNMEISt0ZXN0OkdOWEVHWDRaSFhNUVVSMkI1WE9MM1k1S1R1VET0I1RUZWSVg3TFRJV1I3TFhPMUI%3D%22%2C%0A%20%20%22email%22%3A%20%22%22%0A%20%7D%0A%7D",
          "verification": {}
        },
        "mode": 420,
        "user": {},
        "group": {}
      }
    ]
  },
  "systemd": {},
  "networkd": {},
  "passwd": {}
}

Each machine booted with this Container Linux Config should automatically be authenticated with Quay Enterprise.

Manual login

To temporarily login to a Quay Enterprise account on a machine, run docker login:

$ docker login registry.example.com
Login against server at https://registry.example.com/v1/
Username: myapp+deployment
Password: GNXEGX4Y5J63PQWIOGJHLPGM0B5GUDOBZHXMQUR2B5XOL35EFVIX7LTIWR7LXO1B
Email: myemail@example.com

Test push or pull

Now that your machine is authenticated, try pulling one of your repositories. If you haven't pushed a repository into your Quay Enterprise instance, you will need to tag it with the full name:

$ docker tag bf60637a656c registry.domain.com/myapp
$ docker push registry.domain.com/myapp

If you already have images in your registry, test out a pull:

docker pull registry.domain.com/myapp

Pulling via systemd

Assuming a .dockercfg is present in /root, the following is an example systemd unit file that pulls a docker image:

[Unit]
Description=Hello World

[Service]
WorkingDirectory=/root
ExecStartPre=-/usr/bin/docker kill hello-world
ExecStartPre=-/usr/bin/docker rm -f hello-world
ExecStartPre=/usr/bin/docker pull quay.io/example/hello-world:latest
ExecStart=/usr/bin/docker run --rm --name hello-world quay.io/example/hello-world:latest
ExecStop=-/usr/bin/docker stop hello-world

If the working directory is not set, docker will not be able to discover the .dockercfg file and will not have the credentials to pull private images.