SupportConsoleDevelopersStart a trialContact

Authentication

builds for Red Hat OpenShift 1.2

Understanding authentication at runtime

Red Hat OpenShift Documentation Team

Abstract

This document provides information about authentication at runtime.

Chapter 1. Understanding authentication at runtime

When building images, you might need to define authentication in the following scenarios:

  • Authenticating to a container registry
  • Pulling source code from Git

The authentication is done through the definition of secrets in which the required sensitive data is stored.

1.1. Build secret annotation

You can add an annotation build.shipwright.io/referenced.secret: "true" to a build secret. Based on this annotation, the build controller takes a reconcile action when an event, such as create, update, or delete triggers for the build secret. The following example shows the usage of an annotation with a secret: 

apiVersion: v1
data:
  .dockerconfigjson: <pull_secret> 1
kind: Secret
metadata:
  annotations:
    build.shipwright.io/referenced.secret: "true" 2
  name: secret-docker
type: kubernetes.io/dockerconfigjson
1
Base64-encoded pull secret.
2
The value of the build.shipwright.io/referenced.secret annotation is set to true.

This annotation filters secrets which are not referenced in a build instance. For example, if a secret does not have this annotation, the build controller does not reconcile even if the event is triggered for the secret. Reconciling on triggering of events allows the build controller to re-trigger validations on the build configuration, helping you to understand if a dependency is missing.

1.2. Authentication to Git repositories

You can define the following types of authentication for a Git repository:

  • Basic authentication
  • Secure Shell (SSH) authentication

You can also configure Git secrets with both types of authentication in your Build CR.

1.2.1. Basic authentication

With basic authentication, you must configure the user name and password of the Git repository. The following example shows the usage of basic authentication for Git: 

apiVersion: v1
kind: Secret
metadata:
  name: secret-git-basic-auth
  annotations:
    build.shipwright.io/referenced.secret: "true"
type: kubernetes.io/basic-auth 1
stringData: 2
  username: <cleartext_username>
  password: <cleartext_password>
1
The type of the Kubernetes secret.
2
The field to store your user name and password in clear text.

1.2.2. SSH authentication

With SSH authentication, you must configure the Tekton annotations to specify the hostname of the Git repository provider for use. For example, github.com for GitHub or gitlab.com for GitLab.

The following example shows the usage of SSH authentication for Git: 

apiVersion: v1
kind: Secret
metadata:
  name: secret-git-ssh-auth
  annotations:
    build.shipwright.io/referenced.secret: "true"
type: kubernetes.io/ssh-auth 1
data:
  ssh-privatekey: |   2
    # Insert ssh private key, base64 encoded
1
The type of the Kubernetes secret.
2
Base64 encoding of the SSH key used to authenticate into Git. You can generate this key by using the base64 ~/.ssh/id_rsa.pub command, where ~/.ssh/id_rsa.pub denotes the default location of the key that is generally used to authenticate to Git.

1.2.3. Usage of Git secret

After creating a secret in the relevant namespace, you can reference it in your Build custom resource (CR). You can configure a Git secret with both types of authentication.

The following example shows the usage of a Git secret with SSH authentication type: 

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

The following example shows the usage of a Git secret with basic authentication type: 

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

1.3. Authentication to container registries

To push images to a private container registry, you must define a secret in the respective namespace and then reference it in your Build custom resource (CR).

Procedure

  1. Run the following command to generate a secret: 

    $ oc --namespace <namespace> create secret docker-registry <container_registry_secret_name> \
  --docker-server=<registry_host> \ 1
  --docker-username=<username> \ 2
  --docker-password=<password> \ 3
  --docker-email=<email_address>
    1
    The <registry_host> value denotes the URL in this format https://<registry_server>/<registry_host>.
    2
    The <username> value is the user ID.
    3
    The <password> value can be your container registry password or an access token.

  2. Run the following command to annotate the secret: 

    $ oc --namespace <namespace> annotate secrets <container_registry_secret_name> build.shipwright.io/referenced.secret='true'

  3. Set the value of the spec.output.pushSecret field to the secret name in your Build CR: 

    apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: buildah-golang-build
  # ...
  output:
    image: <path_to_image>
    pushSecret: <container_registry_secret_name>

1.4. Role-based access control

The release deployment YAML file includes two cluster-wide roles for using Builds objects. The following roles are installed by default:

  • shpwright-build-aggregate-view: Grants you read access to the Builds resources, such as BuildStrategy, ClusterBuildStrategy, Build, and BuildRun. This role is aggregated to the Kubernetes view role.
  • shipwright-build-aggregate-edit: Grants you write access to the Builds resources that are configured at namespace level. The build resources include BuildStrategy, Build, and BuildRun. Read access is granted to all ClusterBuildStrategy resources. This role is aggregated to the Kubernetes edit and admin roles.

Only cluster administrators have write access to the ClusterBuildStrategy resources. You can change this setting by creating a separate Kubernetes ClusterRole role with these permissions and binding the role to appropriate users.

Legal Notice

Copyright © 2024 Red Hat, Inc.

OpenShift documentation is licensed under the Apache License 2.0 (https://www.apache.org/licenses/LICENSE-2.0).

Modified versions must remove all Red Hat trademarks.

Portions adapted from https://github.com/kubernetes-incubator/service-catalog/ with modifications by Red Hat.

Red Hat, Red Hat Enterprise Linux, the Red Hat logo, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

Java® is a registered trademark of Oracle and/or its affiliates.

XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.

MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.

Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.

The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation’s permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.