Install the Openshift CLI

Step 0 is to install the Openshift CLI. I generally find CLIs easier to use + understand, but Openshift also has a nice GUI you can use if you'd prefer.

Note: this assumes that you already have access to and Openshift instance.

• Download
• Untar tar -xvzf openshift-origin-client-tools-v1.5.1-7b451fc-linux-64bit.tar.gz
• Move binary into path mv openshift-origin-client-tools-v1.5.1-7b451fc-linux-64bit/oc /usr/local/bin

Note: If you're not sure what's in your path, run echo $PATH

Create an Openshift project

This is where our applications, builds, etc. will live. I highly recommend running oc new-project -h first to see if there are any flags or arguments you want to pass in! I just ran oc new-project <project-name>

Pause

Stop right here! Usually, the tutorials will tell you to make your Openshift application next and pass in your Git URL. DON'T FALL FOR IT. The problem is that for private repos, you need to have a deploy key so Openshift can authenticate with the repo. However, the only way to tell Openshift it needs the SSH key is in the buildconfig. And the buildconfig isn't generated until you either:

1. Try to create an application (the first build will fail then you can modify the buildconfig) OR
2. Have a template (basically write your own reusable buildconfig).

I ended up using a template, because it drove me nuts to have the first build of the application fail. But you can see a step-by-step guide for option 1 here if you'd prefer to modify an existing buildconfig.

Create an SSH Key

Ok, so, adding a deploy key to both our Github and Openshift. First things first, lets make a special key (Don't use your own personal SSH key! Make a new one!)

ssh-keygen -t rsa -b 4096 -C "openshift-key".

Note: Make sure you give it a unique path, so that it doesn't overwrite any existing SSH key(s)!

Add Public Key as a Deploy Key to Repo

Now we'll add the public key to our private Git repo as a deploy key, so that it can verify communications with Openshift. See Git's slightly more helpful documentation on how to do this here

• Go to the repos main page in Github
• Click the 'Settings' tab
• Go to 'Deploy keys'
• Give it a name (can be anything)
• Paste the public key (~/.ssh/id_rsa-openshift.pub) into the textbox
• Click add key

Add Key as a Secret to Openshift

Now we have to give Openshift the private key, and make it an Openshift secret. Openshift secrets "decouple sensitive content from the pods that use it and can be mounted into containers using a volume plug-in or used by the system to perform actions on behalf of a pod", which is very useful! Creating them requires a few steps (read more about why in this poorly named blog post).

oc secrets new-sshauth openshiftkey --ssh-privatekey=$HOME/.ssh/id_rsa-openshift
oc secrets add serviceaccount/builder secrets/openshiftkey

If you accidentally add the public key like I did, you can remove secrets using oc delete secret openshiftkey

Create Openshift Application

Ok, now that our keys are all squared away, we can create an application using a private git repo as our source! Unfortunately, there's currently no way to use the oc new-app command directly to build an image from a private repo. What we'll do instead is create an application template that includes the necessary secret and use that template to create our app.

• Create a template for our git repo using the new-app command

  oc new-app ssh://git@github.com:mygituser/mygitrepo --name app-name -o json >> my-template.json
  

• Open the JSON file and change "List" to "Template", and "items" to "objects".

• Add a "name": "my-app-name" to the metadata object

  "metadata": {"name": "my-app-name"},
  

• This part is tricky and I'm not sure how best to describe it, but in "spec": {"source":{}} object add

  "sourceSecret": {
      "name": "openshiftkey"
  }
  

So you should end up with a block that looks like:

"spec": {
...
    "source": {
        "type": "Git",
        "git": {
            "uri":"ssh://git@github.com/puppetlabs/pe-console-ui-code-coverage"
        },
        "sourceSecret": { "name": "openshiftkey" }
    }
}

This is what my JSON template ended up looking like (with sensitive information removed)

• Create a template based on this json file

  oc create -f my-template.json
  

• Finally, create an application using the template!

  oc new-app --template app-name
  

Again, I highly recommend you run oc new-app -h first to see if there are any special configurations you want to use.

Make Sure It Worked

Run oc get builds, and you should see output similar to this:

NAME      TYPE      FROM          STATUS     STARTED        DURATION
my-app1   Source    Git@abcdefg   Complete   18 hours ago   29s

The Wrong Git URI

At first I was using the http Git URI, which obviously didn't use the SSH deploy key. I then tried using ssh://git@github.com:my-user/my-repo.git, which also failed. git@github.com:my-user/my-repo.git is the right URI!

Application Already Exists

Because I had to try building my application several times, I also had to delete my failed attempts several times so there wouldn't be name errors. I usually ran the following:

oc delete all --selector app=app-name

This should delete all resources for the app