Authentication during builds

The following document provides an introduction around the different authentication methods that can take place during an image build when using the Build controller.

• Overview
• Build Secrets Annotation
• Authentication for Git
  • Basic authentication
  • SSH authentication
  • Usage of git secret
• Authentication to container registries
  • Docker Hub
  • Usage of registry secret
• References

Overview

There are two places where users might need to define authentication when building images. Authentication to a container registry is the most common one, but also users might have the need to define authentications for pulling source-code from Git. Overall, the authentication is done via the definition of secrets in which the require sensitive data will be stored.

Build Secrets Annotation

Users need to add an annotation build.shipwright.io/referenced.secret: "true" to a build secret so that build controller can decide to take a reconcile action when a secret event (create, update and delete) happens. Below is a secret example with build annotation:

apiVersion: v1
data:
  .dockerconfigjson: xxxxx
kind: Secret
metadata:
  annotations:
    build.shipwright.io/referenced.secret: "true"
  name: secret-docker
type: kubernetes.io/dockerconfigjson

This annotation will help us filter secrets which are not referenced on a Build instance. That means if a secret doesn’t have this annotation, then although event happens on this secret, Build controller will not reconcile. Being able to reconcile on secrets events allow the Build controller to re-trigger validations on the Build configuration, allowing users to understand if a dependency is missing.

If you are using kubectl command create secrets, then you can first create build secret using kubectl create secret command and annotate this secret using kubectl annotate secrets. Below is an example:

kubectl -n ${namespace} create secret docker-registry example-secret --docker-server=${docker-server} --docker-username="${username}" --docker-password="${password}" --docker-email=me@here.com
kubectl -n ${namespace} annotate secrets example-secret build.shipwright.io/referenced.secret='true'

Authentication for Git

There are two ways for authenticating into Git (applies to both GitLab or GitHub): SSH and basic authentication.

SSH authentication

For the SSH authentication you must use the tekton annotations to specify the hostname(s) of the git repository providers that you use. This is github.com for GitHub, or gitlab.com for GitLab.

As seen in the following example, there are three things to notice:

• The Kubernetes secret should be of the type kubernetes.io/ssh-auth
• The data.ssh-privatekey can be generated by following the command example base64 <~/.ssh/id_rsa, where ~/.ssh/id_rsa is the key used to authenticate into Git.

apiVersion: v1
kind: Secret
metadata:
  name: secret-git-ssh-auth
  annotations:
    build.shipwright.io/referenced.secret: "true"
type: kubernetes.io/ssh-auth
data:
  ssh-privatekey: <base64 <~/.ssh/id_rsa>

Basic authentication

The Basic authentication is very similar to the ssh one, but with the following differences:

• The Kubernetes secret should be of the type kubernetes.io/basic-auth
• The stringData should host your user and password in clear text.

apiVersion: v1
kind: Secret
metadata:
  name: secret-git-basic-auth
  annotations:
    build.shipwright.io/referenced.secret: "true"
type: kubernetes.io/basic-auth
stringData:
  username: <cleartext username>
  password: <cleartext password>

Usage of git secret

With the right secret in place(note: Ensure creation of secret in the proper Kubernetes namespace), users should reference it on their Build YAML definitions.

Depending on the secret type, there are two ways of doing this:

When using ssh auth, users should follow:

apiVersion: shipwright.io/v1alpha1
kind: Build
metadata:
  name: buildah-golang-build
spec:
  source:
    url: git@gitlab.com:eduardooli/newtaxi.git
    credentials:
      name: secret-git-ssh-auth

When using basic auth, users should follow:

apiVersion: shipwright.io/v1alpha1
kind: Build
metadata:
  name: buildah-golang-build
spec:
  source:
    url: https://gitlab.com/eduardooli/newtaxi.git
    credentials:
      name: secret-git-basic-auth

Authentication to container registries

For pushing images to private registries, users require to define a secret in their respective namespace.

Docker Hub

Follow the following command to generate your secret:

kubectl --namespace <YOUR_NAMESPACE> create secret docker-registry <CONTAINER_REGISTRY_SECRET_NAME> \
  --docker-server=<REGISTRY_HOST> \
  --docker-username=<USERNAME> \
  --docker-password=<PASSWORD> \
  --docker-email=me@here.com
kubectl --namespace <YOUR_NAMESPACE> annotate secrets <CONTAINER_REGISTRY_SECRET_NAME> build.shipwright.io/referenced.secret='true'

Notes: When generating a secret to access docker hub, the REGISTRY_HOST value should be https://index.docker.io/v1/, the username is the Docker ID. Notes: The value of PASSWORD can be your user docker hub password, or an access token. A docker access token can be created via Account Settings, then Security in the sidebar, and the New Access Token button.

Usage of registry secret

With the right secret in place (note: Ensure creation of secret in the proper Kubernetes namespace), users should reference it on their Build YAML definitions. For container registries, the secret should be placed under the spec.output.credentials path.

apiVersion: shipwright.io/v1alpha1
kind: Build
metadata:
  name: buildah-golang-build
  ...
  output:
    image: docker.io/foobar/sample:latest
    credentials:
      name: <CONTAINER_REGISTRY_SECRET_NAME>

References

See more information in the official Tekton documentation for authentication.