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
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.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 encoded1.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-authThe 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-auth1.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
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>
Run the following command to annotate the secret:
$ oc --namespace <namespace> annotate secrets <container_registry_secret_name> build.shipwright.io/referenced.secret='true'
Set the value of the
spec.output.pushSecretfield to the secret name in yourBuildCR: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 asBuildStrategy,ClusterBuildStrategy,Build, andBuildRun. This role is aggregated to the Kubernetesviewrole. -
shipwright-build-aggregate-edit: Grants you write access to the Builds resources that are configured at namespace level. The build resources includeBuildStrategy,Build, andBuildRun. Read access is granted to allClusterBuildStrategyresources. This role is aggregated to the Kuberneteseditandadminroles.
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.
