Deploying InterSystems IRIS solution on GKE Using GitHub Actions

In an earlier article (hope, you’ve read it), we took a look at the CircleCI deployment system, which integrates perfectly with GitHub. Why then would we want to look any further? Well, GitHub has its own CI/CD platform called GitHub Actions, which is worth exploring. With GitHub Actions, you don’t need to rely on some external, albeit cool, service.

In this article we’re going to try using GitHub Actions to deploy the server part of  InterSystems Package Manager, ZPM-registry, on Google Kubernetes Engine (GKE).

As with all systems, the build/deploy process essentially comes down to “do this, go there, do that,” and so on. With GitHub Actions, each such action is a job that consists of one or more steps, together known as a workflow. GitHub will search for a description of the workflow in the YAML file (any filename ending in .yml or .yaml) in your .github/workflows directory. See Core concepts for GitHub Actions for more details.

All further actions will be performed in the fork of the ZPM-registry repository. We’ll call this fork "zpm-registry" and refer to its root directory as "<root_repo_dir>" throughout this article. To learn more about the ZPM application itself see Introducing InterSystems ObjectScript Package Manager and The Anatomy of ZPM Module: Packaging Your InterSystems Solution.

All code samples are stored in this repository to simplify copying and pasting. The prerequisites are the same as in the article Automating GKE creation on CircleCI builds.

We’ll assume you’ve read the earlier article and already have a Google account, and that you’ve created a project named "Development," as in the previous article. In this article, its ID is shown as <PROJECT_ID>. In the examples below, change it to the ID of your own project.

Keep in mind that Google isn’t free, although it has a free tier. Be sure to control your expenses.

 

Workflow Basics

Let’s get started. 

A simple and useless workflow file might look like this:

 

When pushing to the repository, you need to execute a job named "Greeting," which consists of a single step: printing a welcome phrase. The job should run on a GitHub-hosted virtual machine called the Runner, with the latest version of Ubuntu installed.
After pushing this file to the repository, you should see on the Code GitHub tab that everything went well:

 

If the job had failed, you’d see a red X instead of a green checkmark. To see more, click on the green checkmark and then on Details. Or you can immediately go to the Actions tab:

 

You can learn all about the workflow syntax in the help document Workflow syntax for GitHub Actions.

If your repository contains a Dockerfile for the image build, you could replace the "Hello world" step with something more useful like this example from starter-workflows:

 

Notice that a new step, "uses: action/checkout@v2", was added here. Judging by the name "checkout", it clones the repository, but where to find out more? 

As in the case of CircleCI, many useful steps don’t need to be rewritten. Instead, you can take them from the shared resource called Marketplace. Look there for the desired action, and note that it’s better to take those that are marked as "By actions" (when you hover over - "Creator verified by Github").

 

 

The "uses" clause in the workflow reflects our intention to use a ready-made module, rather than writing one ourselves.

The implementations of the actions themselves can be written in almost any language, but JavaScript is preferred. If your action is written in JavaScript (or TypeScript), it will be executed directly on the Runner machine. For other implementations, the Docker container you specify will run with the desired environment inside, which is obviously somewhat slower. You can read more about actions in the aptly titled article, About actions. 

The checkout action is written in TypeScript. And in our example, Terraform action is a regular bash script launched in Docker Alpine.

There’s a Dockerfile in our cloned repository, so let's try to apply our new knowledge. We’ll build the image of the ZPM registry and push it into the Google Container Registry. In parallel, we’ll create the Kubernetes cluster in which this image will run, and we’ll use Kubernetes manifests to do this. 

Here’s what our plan, in a language that GitHub understands, will look like (but keep in mind that this is a bird's eye view with many lines omitted for simplification, so don’t actually use this config):

 

This is the skeleton of the working config in which there are no muscles, the real actions for each step. Actions can be accomplished with a simple console command ("run" or "run |" if there are several commands):          

 

You can also launch actions as a module with "uses":

 

By default, all jobs run in parallel, and the steps in them are done in sequence. But by using "needs", you can specify that one job should wait for the rest to complete:

 

By the way, in the GitHub Web interface, such waiting jobs appear only when the jobs they’re waiting for are executed.

The "gke-provisioner" job mentions Terraform, which we examined in the previous article. The preliminary settings for its operation in the GCP environment are repeated for convenience in a separate markdown file. Here are some additional useful links:

• Terraform Apply Subcommand documentation
• Terraform GitHub Actions repository
• Terraform GitHub Actions documentation

In the "kubernetes-deploy" job, there is a step called "Apply Kubernetes manifests". We’re going to use manifests as mentioned in the article Deploying InterSystems IRIS Solution into GCP Kubernetes Cluster GKE Using CircleCI, but with a slight change.

In the previous articles, IRIS application has been stateless. That is, when restarting the pod, all data is returned to its default place. This is great, and it’s often necessary, but for ZPM registry you need to somehow save the packages that were loaded into it, regardless of how many times you need to restart. Deployment allows you to do this, of course, but not without limitations. 

For stateful applications, it’s better to choose the StatefulSet resource. Pros and cons can be found in the GKE documentation topic on Deployments vs. StatefulSets and the blog post Kubernetes Persistent Volumes with Deployment and StatefulSet.

The StatefulSet resource is in the repository. Here’s the part that’s important for us:

 

The code creates a 10GB read/write disk that can be mounted by a single Kubernetes worker node. This disk (and the data on it) will survive the restart of the application. It can also survive the removal of the entire StatefulSet, but for this you need to set the correct Reclaim Policy, which we won’t cover here.

Before breathing life into our workflow, let's add a few more variables to GitHub Secrets:

 

 

The following table explains the meaning of these settings (service account keys are also present):

 

For SERVICE_ACCOUNT_KEY, if your JSON-key has a name, for instance, key.json, run the following command:

 

For TF_SERVICE_ACCOUNT_KEY, note that its rights are described in Automating GKE creation on CircleCI builds.

One small note about SERVICE_ACCOUNT_KEY: if you, like me, initially forgot to convert it to base64 format, you’ll see a screen like this:

 

Now that we’ve looked at the workflow backbone and added the necessary variables, we’re ready to examine the full version of the workflow (<root_repo_dir>/.github/workflow/workflow.yaml):

 

Before you push to a repository, you should take the terraform-code from the Terraform directory of github-gke-zpm-registry repository, replace placeholders as noted in main.tf comment, and put it inside the terraform/ directory. Remember that Terraform uses a remote bucket that should be initially created as noted in Automating GKE creation on CircleCI builds article.

Also, Kubernetes-code should be taken from the K8S directory of github-gke-zpm-registry repository and put inside the k8s/ directory. These code sources were omitted in this article to save space. 

Then you can trigger a deploy:

 

After pushing the changes to our forked ZPM repository, we can take a look at the implementation of the steps we described:
 

 

 

There are only two jobs so far. The third, "kubernetes-deploy", will appear after the completion of those on which it depends.
Note that building and publishing Docker images requires some time:

 

And you can check the result in the GCR console:

 

 

The "Provision GKE cluster" job takes longer the first time as it creates the GKE cluster. You’ll see a waiting screen for a few minutes:

 

 

But, finally, it finishes and you can be happy:

 

 

The Kubernetes resources are also happy:

 

It's a good idea to wait for Running status, then check other things:

 

Even the disks are happy:

 

 

And happiest of all is the ZPM registry (we took the External-IP output of "kubectl -n iris get svc"):

 

Handling the login/password over HTTP is a shame, but I hope to do something about this in future articles.

By the way, you can find more information about endpoints in the source code: see the XData UrlMap section.

We can test this repo by pushing a package to it. There’s a cool ability to push just a direct GitHub link. Let’s try with the math library for InterSystems ObjectScript. Run this from your local machine:

 

Restart a pod to be sure that the data is in place:

 

Wait for a running pod. Then what I hope you’ll see:

 

Let’s install this math package from your repository on your local IRIS instance. Choose the one where the ZPM client is already installed:

 

Congratulations!
Don’t forget to remove the GKE cluster when you don’t need it anymore:
 

 

Conclusion

There are not many references to GitHub Actions within the InterSystems community. I found only one mention from guru @mdaimor. But GitHub Actions can be quite useful for developers storing code on GitHub. Native actions supported only in JavaScript, but this could be dictated by a desire to describe steps in code, which most developers are familiar with. In any case, you can use Docker actions if you don’t know JavaScript.

Regarding the GitHub Actions UI, along the way I discovered  a couple of inconveniences that you should be aware of:

• You cannot check what is going on until a job step is finished. It’s not clickable, like in the step "Terraform apply".
• While you can rerun a failed workflow, I didn’t find a way to rerun a successful workflow. 

A workaround for the second point is to use the command:

 

You can learn more about this in the StackOverflow question How do I re-run Github Actions?