Private Git Repositories: Part 2B – Repository SSH Keys

In this series on using private Git repositories with OpenShift, we started out by looking at the different types of protocols that can be used when accessing a Git repository. We also looked at how these combined with different credential types to control access to a private Git repository.

We then covered using a repository SSH key with a private Git repository hosted by GitHub. This included registering the public key with GitHub, the creation of a secret in OpenShift to hold the private key, and the deployment of an application from source code in the private Git repository, using the HTTPD S2I builder. When working with OpenShift to do this, the web console was used.

In this post, we will revisit the steps performed in OpenShift to create the secret and deploy the application, but this time we will use the command line rather than the web console.

Registering the Private Key with OpenShift

Although we are going to use the command line for interacting with OpenShift, rather than the web console, the same steps are used to create the repository SSH key and register it with GitHub. You can check the previous post for those details.

To register the private key file with OpenShift, the file without the .pub extension, we use the oc secrets new-sshauth command:

$ oc secrets new-sshauth repo-at-github --ssh-privatekey=repo-at-github

To mark that the secret can be used by the OpenShift project builder service account run:

$ oc secrets link builder repo-at-github

When using the web console to create the secret, we were able to link the secret to the builder service account at the same time. When using the command line we need to do this as a separate step.

Creating an Application from the Repository

Next, we want to deploy our application from our private Git repository. In this case, our private Git repository contains some static files we want to serve up using a traditional HTTP web server.

To deploy a static web site in OpenShift we can use the httpd S2I builder image and run the command:

$ oc new-app httpd~git@github.com:openshift-evangelists/private-repo.git --name mysite

Note that as when using the web console, we are using the SSH URI for the private Git repository, not the HTTPS URI.

The oc new-app command when run will output:

--> Found image ea9841a (2 weeks old) in image stream "openshift/httpd" under tag "2.4" for "httpd"

    Apache httpd 2.4
    ----------------
    Apache httpd 2.4 available as docker container, is a powerful, efficient, and extensible web server. Apache supports a variety of features, many implemented as compiled modules which extend the core functionality. These can range from server-side programming language support to authentication schemes. Virtual hosting allows one Apache installation to serve many different Web sites.

    Tags: builder, httpd, httpd24

    * A source build using source code from ssh://git@github.com/openshift-evangelists/private-repo.git will be created
      * The resulting image will be pushed to image stream "mysite:latest"
      * Use 'start-build' to trigger a new build
    * This image will be deployed in deployment config "mysite"
    * Ports 443/tcp, 80/tcp, 8080/tcp, 8443/tcp will be load balanced by service "mysite"
      * Other containers can access this service through the hostname "mysite"
    * This image declares volumes and will default to use non-persistent, host-local storage.
      You can add persistent volumes later by running 'volume dc/mysite --add ...'

--> Creating resources ...
    imagestream "mysite" created
    buildconfig "mysite" created
    deploymentconfig "mysite" created
    service "mysite" created
--> Success
    Build scheduled, use 'oc logs -f bc/mysite' to track its progress.
    Run 'oc status' to view your app.

Running:

$ oc logs -f bc/mysite

to monitor the build process, we will, however, see that the build process failed:

Cloning "ssh://git@github.com/openshift-evangelists/private-repo.git" ...
error: build error: Host key verification failed.
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

This is because it is a private Git repository, and although we created the secret holding the private key for accessing the repository, we didn’t tell OpenShift to use it for this build.

Adding the Secret to the Build Configuration

There are a number of ways which one can associate a repository source secret with a build so that it is used when accessing a private Git repository.

The first way is to let the build fail as has occurred here, then edit the build configuration which was created to add the details of the secret to use. This is necessary as it is not possible to specify the source secret on the command line when running oc new-app.

To modify the build configuration created by the oc new-app command to have it use the secret we can run:

oc set build-secret --source bc/mysite repo-at-github

A new build can then be triggered by running:

oc start-build mysite

Annotating the Secret with the Repository

Letting the initial build fail and only then adding the source secret isn’t an ideal workflow. The better way to associate the source secret with a build is to annotate the secret with the details of which Git repositories it can be used with.

For our example this can be done by running the command:

oc annotate secret/repo-at-github \
    'build.openshift.io/source-secret-match-uri-1=ssh://github.com/openshift-evangelists/private-repo.git'

This is adding a numbered annotation of the form build.openshift.io/source-secret-match-uri-nnn. The number is required as technically the use of a single secret against many repositories is supported and this allows you to add more than one annotation. As mentioned in our first post, it is better that a repository SSH key only be used with a single repository, so we use 1 here and aren’t going to be adding additional annotations.

The value of the annotation we create is the SSH URI for the Git repository, but in this case, it must include ssh:// and not use the shorthand form we used when creating the application. You should however not include any user information, so the git@ is dropped.

Having added the annotation to the secret, we can now use oc new-app to create the application, and OpenShift will automatically use it when the Git repository matches that specified by the annotation.

Adding an annotation in this way means that we can avoid the problem of the initial build failing and going back and editing the build configuration afterwards.

Using annotations on the secret is also useful in the context of where your OpenShift cluster may be using a project template to pre-populate a new project with secrets required to access any private Git repositories used by an organization.

Although we used the command line here to create our application, a secret annotated with the repository will also be used if creating an application from the web console, without you needing to select the source secret.

Using a Personal Access Token

Using a repository SSH key will only work where an OpenShift cluster can access a Git repository hosting service over an SSH connection. If the OpenShift cluster is located behind a firewall, the SSH protocol may be blocked and it would not be possible to use a remote Git repository.

In this case, you would instead need to use a personal access token and a HTTPS connection.

In the next blog post in this series, we will look at how to use a personal access token to access a private Git repository, where the repository is hosted on GitHub.

Access the rest of the series here:

Categories
OpenShift Container Platform, OpenShift Dedicated, OpenShift Ecosystem, OpenShift Online, OpenShift Origin
Tags
,