Your First Pulumi and Shipa Integration

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
Brew installs

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. 

Pulumi Shipa 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 --set-current
shipa login
shipa token show
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

Shipa Framework

Select “reasonable defaults” and click Next. 

Name: pulumiframework

Plan: shipa-plan

Teams: shipa-team

Shipa General Config

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='{}' | 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. 

Shipa Cluster Setup

Click Next and add the connection details.

Shipa Cluster Connection

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. 

Shipa OKE

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

Shipa Pulumi Framework

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

Shipa Pulumi Project

With the Pulumi.yaml created, now you can add the NodeJS dependencies with Yarn.

yarn add @shipa-corp/pulumi
yarn add @pulumi/pulumi
Shipa Yarn

Next export a pair of environmental variables to connect with Shipa Cloud. 

export SHIPA_HOST=
export SHIPA_TOKEN=your_shipa_token
Shipa ENV Variable

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: ""
Shipa Pulumi Index.ts

Take a look at your directory/project to see the following structure is there. 

Shipa Pulumi Project Structure

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:

mv pulumi-resource-shipa $HOME/.pulumi/bin
Add Pulumi Plugin

Now you are ready to execute! CD back into your project folder. 

Pulumi 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. 

Shipa Pulumi Execution

Note: If using a Mac, you might have to trust the plugin. If so, trust and re-run. 

Mac Shipa Warning

Navigate back to the Shipa Cloud Dashboard and step into the Application and check out your deployed app with the Endpoint.

Shipa Deployed Pulumi App

Click on the Endpoint and ta-da!

Deployed Kubernetes Pulumi

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.