OPENSHIFT FOR DEVELOPERS

Building your Applications in OpenShift from a GitHub Private Repository

When you have no idea where to start

Downtown Brownsvile, Texas

In this article, we would cover the details of building an application in OpenShift from a private GitHub repository. In general, this will be the case when building most applications. This article can be summarized with the following steps:

1. Generate an SSH key pair (private + public) using the ssh-keygen tool.
2. Create a secret object in OpenShift to store the private SSH key.
3. Add the public SSH key to the GitHub repository.
4. Edit the build configuration for an application in OpenShift to use the SSH GitHub URL and provide the secret containing the private SSH key.

Note: If the repository view is set to public, there is no need to provide the Git credentials to your repository. 

When a Build Fails Because the Repository is Visibility is Set to Private

Suppose that you are building an application in OpenShift from a private repository. In the most simplest form this is how OpenShift builds your image:

1. A base image is pulled from an image registry.
2. OpenShift clones the Git repository into the home directory of the base Python image.
3. The application dependencies are installed
4. After the image is built, the image is stored in the internal image registry.
5. Finally, a pod is spin up, a container with your image application is injected and your application is started

In Step 2, the developer needs to provide the proper GitHub credentials to OpenShift so that OpenShift is able to authenticate and clone the repository successfully. If OpenShift is able to pull the base image (Step 1) but fails at cloning the repository (Step 2), the build will fail as shown in the image below:

Providing the wrong Git credentials or not providing any credentials at all will result in the following error when building from a private repository :

Cloning "https://github.com/user/some-repo.git" ...
error: failed to fetch requested repository "https://githu...k-ceballos/openshift-fastapi.git" with provided credentials

To fix this issue, you will need to provide the correct Git credentials.

Generating SSH Keys

We will use the ssh-keygen tool for creating new authentication key pairs for SSH. This tool should be installed in Mac and Linux operating systems. In newer versions of Windows, you will need to use PowerShell or Git for Windows.

1. Open a terminal and navigate to the home directory using cd ~
2. In the terminal navigate into .ssh hidden folder. To check all the contents (including hidden files and folders) of your current working directory use ls -a — see Figure 1a. If you cannot find the .ssh folder create one with mkdir .ssh. However, make sure that you are not overwriting and existing .ssh hidden folder — see Figure 1b for an example of the contents inside an .ssh folder. SSH keys that are deleted might be lost forever if you don’t have them saved elsewhere so be careful to not overwrite your .ssh folder.

Figure 1 — (a) The contents of my home directory listed with `ls -a` including the hidden files + folders. (b) the contents of my .ssh folder.

3. Once inside the .ssh folder, paste the text below in the terminal, substituting in your GitHub email address and provide a file name.

ssh-keygen -t ed25519 -C "your_email@example.com" -f "ssh-file-name"

You might need to use different options to generate your SSH keys which depend on your environment. To read more about this you can check out the GitHub documentation for generating SSH keys.

For example, if your email and file name were: frank@gmail.com and my-crazy-project you will run:

ssh-keygen -t ed25519 -C "frank@gmail.com" -f "my-crazy-project"

Figure 2 — (a) after running the ssh-keygen command you will prompt to enter a passphrase. Simply hit the Enter key twice. (b) if you are able to successfully generate the SSH keys, you should see a bunch of text with information about the new keys.

After running ssh-keygen command, you will be prompt to enter a passphrase. Simply hit the Enter key twice (see Figure 2a). After successfully generating the SSH keys, you should see text describing additional details about your keys — see Figure 2b. In Figure 2b, notice that the following files were generated (see Figure 3):

• my-crazy-project: This is the private part of the key. Later, we will save this in an OpenShift secret .
• my-crazy-project.pub : This is the public part of the key that we will later add to GitHub repository Deploy keys.

Figure 3— Newly generate SSH keys inside the .ssh folder.

Let’s inspect this SSH keys using the cat tool — see Figure 4. Feel free to use your favorite editor.

Figure 4 — (a) example of a public SSH key and (b) private SSH key

In Figure 4, notice how the public and private key look different. Remember this so that you don’t make the mistake of adding wrong key to the wrong place.

• The public key goes to GitHub
• The private key goes to OpenShift.

Create Secret in OpenShift

The secret object in OpenShift is used to store sensitive information. In our case, we will create a secret object to store the private SSH key we generated earlier.

Figure 5 — Creating an OpenShift Secret via the web console

To create an secret in OpenShift via the web console — see Figure 5:

1. Switch to Developer mode .
2. Click on Secrets.
3. Hit the Create dropdown and select Source secret. Notice that there are different type of secret objects that you can create. A Source secret object is intended to store the git credentials of your repository.

After selecting Source secret, you will be taken to the Create source secret screen. In here, you will provide the source secret details — as shown in Figure 6.

Figure 6 — Creating a source secret in OpenShift.

In Figure 6, we are creating a secret named git-repository-secret . Feel free to choose a name that is meaningful to your project. After hitting Create, you will be shown the details of the secret object you just created. To view the list of secret objects in your namespace, select Secrets in the sidebar — see Figure 7. In here you should see your newly created secret.

Figure 7 — List of secrets in current namespace. Notice that our new secret is added in here.

Adding the Public SSH key to GitHub

We will add the SSH key to the GitHub repository settings as a deploy key. A deploy key is used to deploy the application in to a cloud platform. For security reasons is important to note that deploy keys usually only need read access. Typically, there is no reason why OpenShift/AWS/Azure need write access to the repository.

To add the public SSH key to the repository as a deploy key — see Figure 8–9: (1) Click on the repository Settings tab. (2) Click on the Deploy keys on the side bar. (3) Click on Add deploy key.

Figure 8 — Accessing the Deploy keys section of the repository.

(4) Provide a key name. (5) Paste the public SSH key in the text box. In here make sure to include every part of the key. (6) Hit Add key.

Figure 9 — Adding public SSH key as a deploy key. After hitting Add key, you might be prompt to provide your GitHub password.

Note that when adding a deploy as shown in Figure 9, we did not allow write access to this key. If your deploy key is successfully added to the repository, you should see it listed under the Deploy keys section — see Figure 10.

Figure 10 — Deploy keys in repository.

You can add as many deploy keys as you want to the Deploy key section. You might want to do this if you are building and deploying your applications into different environments.

Editing an Existing Build Configuration

With almost all the dirty work already done, we will need to grab one more thing — the SSH URL for the repository. To do this, go back to the GitHub repository Code section. (1) Hit on the Code dropdown, (2) Select the SSH tab, and (3) Copy the SSH URL — see Figure 11.

Figure 11 — Copying SSH URL from GitHub repository.

The SSH URL should start with: git@github.com . Don’t use the HTTPS URL which starts with https://. Remember we are using the SSH protocol to clone the repository.

Back to OpenShift.

If you already have started the build process for you application in OpenShift, you should be able to find the build configuration for your application under the Builds section — see Figure 12.

Figure 12 — Accessing an existing build configuration.

Once you access the build configuration for your application, select Edit BuildConfig from the Action dropdown — see Figure 13.

Figure 13-Build configuration section for an application called openshift-fastapi-git.

In the Edit BuildConfig section: (1) Add the SSH URL, (2) Click on Show Advanced Git Options, (3) From Source Secret dropdown select your private SSH key, and (4) hit Save — as shown in Figure 14.

Figure 14 — Adding SSH URL and Git secret to the build configuration.

After saving the changes, we will need to kick of a new build. To do so, go back to the build configuration details section as shown in. Figure 12. In the Actions dropdown shown in Figure 13, select Start build.

Figure 15-List of builds. After starting a new build you should see a new build running.

This will start a new build. To see the builds logs click on the Builds tab,find the current running build from list, and once in the Build Details section, click on the Logs tab — see Figure 15.

If you see a message similar to this in the logs:

Cloning "git@github.com:frank-ceballos/openshift-fastapi.git" ...  Commit: b7e2bdfcabbec4bc76d98336ee2f59e94a8d8ba9 (Merge pull request #1 from frank-ceballos/dev)  Author: Frank Ceballos <frank.ceballos123@gmail.com>  Date: Wed Jan 12 19:00:44 2022 -0600

This means OpenShift was able to successfully clone your repository! Awesome!

Closing Remarks

You should now be able to build your applications in OpenShift from a private GitHub repository.

We would like to mentioned that your organization might have different key requirements — for security — when it comes to generating and using SSH keys. You might need to contact the IT group if you are having issues with kicking of a build from your private repository.

Find me at LinkedIn. Until next time! Take care and code everyday!

Frank Ceballos

Frank Ceballos — Postdoctoral Fellow — Medical College of Wisconsin | LinkedIn

frank-ceballos — Overview