Typically, Infrastructure-as-Code or IaCs have had their own languages to learn. For example, if leveraging Terraform most likely you came across Terraform’s native syntax, HCL. Though as software engineers we might be more familiar with other languages of choice. Using a general-purpose computer language vs a provider level syntax does unlock the power of the language; anything you can do in the computer language potentially can be additional methods, calls, etc. Pulumi is exactly that, an IaC that is in your language of choice. In this example, we will run through a NodeJS example with Pulumi and Shipa Cloud to deploy an application to Kubernetes.
Getting Started with Pulumi and NodeJS
If this is your first time using Pulumi or NodeJS, don’t worry we will walk you through how to execute this example. You will first need the language [NodeJS] runtime and the Pulumi CLI to run the example. Additionally, to install the Pulumi and Shipa NodeJS dependencies, the quickest way is Yarn. The easiest way to install these packages if you are using a Mac is Homebrew.
brew install nodejs brew install pulumi brew install yarn node -v pulumi version yarn -version
Once those are installed, you are now ready to create the Pulimi project structure.
Create a folder called “pulumi-shipa”. This will be the base of the project.
Next, let’s get setup on Shipa Cloud.
As Much or as little IaC as You Need
The beauty of Shipa is that you can use as much or as little of Infrastructure-as-Code as you chose. The Shipa abstraction stays the same so you can mix and match IaCs. The art of the possible is laid out in the One Line Developer Experience blog post. If you don’t have a Shipa Cloud account, sign up for a free account. For example purposes, we will just deploy an application using Pulumi. The Shipa Abstractions e.g the Shipa Framework and Kubernetes Cluster connection can be set up via the UI.
Once you signed in to Shipa Cloud, you will need to get the Shipa CLI to grab an authentication token to use later at Pulumi execution time.
shipa target add shipa-cloud target.shipa.cloud --set-current shipa login shipa token show
With the Shipa Cloud account and Shipa CLI wired, time to create a few Shipa objects and bind to a Kubernetes cluster.
Getting Started with Shipa Cloud
To deploy workloads with Shipa Cloud, you will need to have a Kubernetes cluster. There are several ways to acquire one from using a cloud vendor or even locally something like K3d. Shipa works off a Framework Concept; a logical grouping of abstractions and policies.
To create your first Shipa Framework, head to the dashboard.
Shipa Cloud -> Frameworks -> +Create Framework
Select “reasonable defaults” and click Next.
Name: pulumiframework
Plan: shipa-plan
Teams: shipa-team
Click Create and then your Framework will be ready.
The next step is to bind/connect a Kubernetes cluster to shipa. There are three items that Shipa needs to know about your cluster. The Kubernetes API Endpoint, the Shipa Role Token, and CA Certificate. Gather these three pieces of information and can add a Cluster to Shipa.
Kubernetes Endpoint API
kubectl cluster-info | grep 'Kubernetes' | awk '/http/ {print $NF}'
Shipa Role Token
Apply the shipa-admin-service-account.yaml from here and 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}')
CA Cert
kubectl get secret $(kubectl get secret | grep default-token | awk '{print $1}') -o jsonpath='{.data.ca.crt}' | base64 --decode
With these three pieces of information, you can connect to your Kubernetes cluster.
Shipa Cloud -> Clusters -> +Add Cluster
Name: Can give any name. I am using Oracle Kubernetes so I named it “oke”.
Frameworks: You can bind the Framework you just created e.g pulumiframework at this time.
Click Next and add the connection details.
Then Click Next, then you can ship the Ingress controller setup since can leverage Shipa’s default. After a few moments, your Kubernetes cluster will be ready for workload.
With the Framework and Cluster out of the way, you can leverage the UI to lay down a Shipa Application.
Shipa Cloud -> Applications -> +Create Applications
Name: pulumiapp
Framework: pulumiframework
Team: shipa-team
Click Create and now you can deploy through Pulumi.
Deploying Your App on Kubernetes with Pulumi and Shipa
Now you are ready to create a Pulumi Project and then wire in an Application Deployment.
If this is your first time using Pulumi, you will need to register with Pulumi for example with your GitHub credentials.
Create a Pulumi Project
Head back to your /pulumi-shipa folder and create a Pulumi.yaml file. A Pulumi Project is anywhere that file is located.
name: pulumi-shipa-nodejs runtime: nodejs description: Creating a Shipa App with Pulumi
With the Pulumi.yaml created, now you can add the NodeJS dependencies with Yarn.
yarn add @shipa-corp/pulumi yarn add @pulumi/pulumi
Next export a pair of environmental variables to connect with Shipa Cloud.
export SHIPA_HOST=https://target.shipa.cloud:8081
export SHIPA_TOKEN=your_shipa_token
Now you can create/add the NodeJS file to deploy your application e,g “pulumiapp”. Can add the following index.ts in the root of your directory/project. Can take a note at the “app” and “image” fields.
import * as pulumi from “@pulumi/pulumi”;
import * as pulumi from "@pulumi/pulumi";
import * as shipa from "@shipa-corp/pulumi";
const appDeploy = new shipa.AppDeploy("app-deploy", {
app: "pulumiapp",
deploy: {
image: "docker.io/shipasoftware/bulletinboard:1.0"
}
});
Take a look at your directory/project to see the following structure is there.
Now you are ready to execute the example.
Run Your Example
First, you will need to download and install the Shipa Pulumi Provider and place on your path.
Download and expand: https://storage.googleapis.com/shipa-pulumi/pulumi-resource-shipa.zip
mv pulumi-resource-shipa $HOME/.pulumi/bin
Now you are ready to execute! CD back into your project folder.
With a simple “pulumi up”, you are now ready to execute.
pulumi up
When prompted to enter a stack, can say “dev”. Say yes to updating.
Note: If using a Mac, you might have to trust the plugin. If so, trust and re-run.
Navigate back to the Shipa Cloud Dashboard and step into the Application and check out your deployed app with the Endpoint.
Click on the Endpoint and ta-da!
And just like that, you are up and started with Pulumi and Shipa. The merging of IaC and AaC [Application-as-Code, Shipa] is a powerful paradigm. Make sure to catch our upcoming webinar in March where we discuss this in greater detail with Pulumi.
Cheers,
-Ravi
