As a software engineer, leveraging GitHub is one of those tools that transcend your personal and professional development activities. Bringing open source to the masses, GitHub is a familiar platform for many. A newer addition to the GitHub Platform is GitHub Actions which was originally a workflow engine, now expanding into CI/CD. Combining the ubiquity of GitHub Actions to your GitHub project/repository with the powerful application abstractions that Shipa provides is a great developer experience.
Example Flow
This example will be designed for a lower barrier of entry. Both GitHub Actions and Shipa can build from source. Shipa leverages Buildpacks to build by convention or can leverage GitHub Actions’ CI [continuous integration] capabilities to do so. This example will assume you have an image available. You will need a Kubernetes cluster to wire to Shipa Cloud. If you are looking at how to build from source e.g before you have an image, Daniele Fontani has an amazing example starting from source code to deployment.
Getting Started
You will need to have a GitHub Account and a Shipa Cloud Account. Also, you will need access to a Docker Registry and a Kubernetes Cluster. If you don’t have a project you are working on, you can clone/fork our example project which is a watered-down version of podinfo pointing to the Docker Hub image of that. Also, feel free to fork my rendition of the example project to make modifications to your specific Shipa Cloud instance. To authenticate with Shipa Cloud with external systems, the Shipa CLI can be used to create/expose a token.
GitHub Actions 101 if this is your first time, the genesis of a GitHub Action is in a .github folder in your project and can have a .github/workflows folder to house the GitHub Actions Workflows.
Investigating the contents of the .github/workflows folder exposes the Shipa Wiring in a GitHub Actions Workflow. The amount of Shipa Wiring is up to you e.g vs using the Shipa UI for a quick example.
Shipa / GitHub Wiring
Depending on how you want to configure your example, you can have GitHub Actions lay down all of the Shipa Objects needed for the abstraction to execute. In my fork of the sample project, is a simpler approach focusing on one release/application e.g a singular image.
Framework
Shipa works off a concept of Frameworks which are the policies and definitions of the application abstraction such as networking policies.
Cluster
A Kubernetes cluster where Shipa will apply it’s Framework to and also has the ability to deploy an Application. A cluster can have multiple Shipa Frameworks for multiple policies and abstractions. To wire a Kubernetes cluster to Shipa, you need to install a Shipa Role Binding to the Kubernetes cluster(s).
Application
An Application is a deployable unit. The Shipa Application is made up of either source code, an image, and additional optional instructions on how to run the Application.
Creating all of those objects requires a few destinations and authentication items that can be wired as secrets in GitHub or represented as flat files in the repo.
GitHub Secrets to Create
Here are the secrets to create to leverage this example. Note that the Cluster-related secrets are prone, especially the certificate, to characters being added into the copy and paste depending on your operating system. Bruno’s example can wire the certificate as a flat-file to validate if additional characters are being added. Future enhancements of the GitHub Action will look to trim these characters.
Repository -> Settings -> Secrets + New repository secret
SHIPA_TOKEN
The Shipa Token is an authentication token to your Shipa instance. With your Shipa CLI, can run the shipa token show command.
shipa token show
SHIPA_HOST
The Shipa Host is the address of your Shipa API. For Shipa Cloud this is
https://target.shipa.cloud:8081
The Kubernetes Cluster Information will need to be added as flat files in your repository in the ./infra folder.
e.g the cluster-def.yaml will be the following and the addresses, caCert, and token will be populated with the following:
cluster:
name: gha-created-cluster
endpoint:
addresses:
- https://someKubernetesEndpoint.com:6443
caCert: ./infra/ca.crt
token: ./infra/token
resources:
frameworks:
name: ["gha-policy"]
CLUSTER_ADDRESS
This is for a Kubernetes Cluster. Can run this command to find:
kubectl cluster-info | grep 'Kubernetes' | awk '/http/ {print $NF}'
CLUSTER_TOKEN
The token is based on the Shipa Role Binding. Can apply the role binding YAML into the cluster then grab the token.
kubectl apply -f shipa-admin-service-account.yaml
kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep shipa-admin | awk '{print $1}')
CLUSTER_CERTIFICATE
Lastly will need to grab the cluster certificate.
kubectl get secret $(kubectl get secret | grep default-token | awk '{print $1}') -o jsonpath='{.data.ca.crt}' | base64 --decode
With those pieces of information, you are ready to run your GitHub Actions.
Running Your GitHub Actions
If you forked one of the example repositories, you will need to activate Actions on your Fork. Click on Actions then Activate.
Now you are able to make a change let’s say in the Prod App folder. The GitHub Actions is wired to look for a push. For example, here you can modify one of the environmental variables and Commit.
Once you Commit, the Action will be kicked off.
Once the Action runs, you can navigate back to the Shipa UI and grab the endpoint of the application.
Shipa Cloud -> Applications -> gha-app -> Endpoint
Clicking on the endpoint will bring you to your running application.
Just like that, your application is deployed. Providing this abstraction will certainly help you and your organization scale as the push to containerization and microservices increases. There is certainly a lot of the art of the possible with GitHub Actions and Shipa. Be sure to check out our webinar diving deeper into both platforms.
Cheers,
-Ravi
