Shipfast docs

Getting started

This guide takes you from a new workspace to your first release. It takes about 45 minutes with an app you already have as Docker images or a Helm chart.

Words used in Shipfast

Steps

1. Sign in to your workspace and invite your team from Users. Give each person a role.
2. Add a cluster. Connect one you have (see Connect a cluster) or create one in your cloud account (see Create a cluster).
3. Create a template. Add your services as Docker images, Helm charts or Kubernetes YAML, and set variables with defaults.
4. Create an application from the template, choose the cluster, and override the values that differ for this environment.
5. Approve it. Once an application is approved and enabled, Shipfast creates its namespace on the cluster and the agent applies it.
6. Wire your CI so new images are registered automatically (see Releases from CI).

Connect a cluster

Connect any conformant Kubernetes cluster: AKS, k3s, open-source Kubernetes on-prem, or an EKS, GKE or VKE cluster you created yourself.

1. In Clusters, add a cluster and choose to connect an existing one.
2. Open its Installation tab. Shipfast shows a command with a one-time token, valid for 15 minutes.
3. Run it with access to the cluster:

$ kubectl apply -f https://<your-workspace>/k8s/apply/<token>

This installs Metacontroller, a small custom resource and the Shipfast agent in their own namespace, with a service account and the role bindings they need.

How the connection works

• The controller in the cluster polls your workspace over HTTPS for what to apply.
• The agent opens a WebSocket from the cluster to your workspace for live data: events, logs, metrics and the browser terminal.
• Every connection starts from the cluster. No inbound port, VPN or bastion host is needed.

The cluster's status changes to configured after its first sync. You can deploy to it from then on.

Create a cluster

Shipfast can create EKS clusters on AWS, GKE on Google Cloud and VKE on Vultr with Terraform, in your own account.

1. Add the cloud account's credentials once. They are stored encrypted.
2. Choose the provider, region, Kubernetes version and node size.
3. Shipfast runs the Terraform job and streams its log. When it finishes, the agent is installed and the cluster is ready.

Shipfast installs the platform tools your apps need: ingress, cert-manager, KEDA, VPA, Karpenter where supported, and OpenCost.

Releases from CI

Your CI keeps building and pushing images. As its last step it tells Shipfast about the new image, and applications that follow that version are updated on their next sync.

1. Create an API key for the template

Open the template's CI/CD tab and create an API key. Store it as a secret in your CI, for example SHIPFAST_API_KEY. You also need the template's ID, shown on the same tab.

2. Call the versions endpoint

curl --user "project${TEMPLATE_ID}:${SHIPFAST_API_KEY}" \
  --data-urlencode "projectId=${TEMPLATE_ID}" \
  --data-urlencode "title=${COMMIT_TITLE}" \
  --data-urlencode "message=${COMMIT_MESSAGE}" \
  "${SHIPFAST_URL}/api/versions/update?channel=Prod&name=${BRANCH}&build=${BUILD_ID}&image=api&url=${IMAGE}"

Authentication is HTTP Basic: the user is project followed by the template ID, and the password is the template's API key. projectId must be sent in the request body.

GitHub Actions

# .github/workflows/release.yml (last step)
- name: Register version with Shipfast
  run: |
    curl --fail --user "project${{ vars.TEMPLATE_ID }}:${{ secrets.SHIPFAST_API_KEY }}" \
      --data-urlencode "projectId=${{ vars.TEMPLATE_ID }}" \
      --data-urlencode "title=${{ github.event.head_commit.message }}" \
      "${{ vars.SHIPFAST_URL }}/api/versions/update?channel=Prod&name=${{ github.ref_name }}&build=${{ github.run_number }}&image=api&url=${{ env.IMAGE }}"

GitLab CI

register_version:
  stage: deploy
  script:
    - curl --fail --user "project${TEMPLATE_ID}:${SHIPFAST_API_KEY}"
        --data-urlencode "projectId=${TEMPLATE_ID}"
        --data-urlencode "title=${CI_COMMIT_TITLE}"
        "${SHIPFAST_URL}/api/versions/update?channel=Prod&name=${CI_COMMIT_BRANCH}&build=${CI_PIPELINE_ID}&image=api&url=${IMAGE}"

GraphQL API

Shipfast has a public GraphQL API for automation, for example creating an application for each new customer from your own systems.

Access

• An administrator turns on API access for the user in Users.
• That user then has a personal API key. Keys start with UNI. Treat them like passwords.
• Send the key in the x-auth-token header. Requests run as that user, with that user's role.

curl "${SHIPFAST_URL}/unifie-api/graphql/v1" \
  -H "x-auth-token: ${SHIPFAST_USER_API_KEY}" \
  -H "content-type: application/json" \
  -d '{"query":"{ Application_getApplicationsList { id name domain isLive } }"}'

The endpoint serves an interactive explorer with the full schema when you open it in a browser.

Applications

• Application_getApplicationsListLists the applications in your workspace.
• Application_createFromTemplateCreates an application from a template on a cluster. extUuid is your own ID for it. Arguments: templateId, name, clusterId, extUuid, extData.
• Application_getApplicationByExtUuidReturns one application by your ID. Arguments: extUuid.
• Application_updateByExtUuidUpdates an application's settings. Arguments: extUuid, fields.
• Application_approveToRunByExtUuidApproves an application to run. Arguments: extUuid, approve.
• Application_getPodsStatusByExtUuidReturns the current pod status. Arguments: extUuid.
• Application_getPodsMetricsByExtUuidReturns pod CPU and memory use. Arguments: extUuid.
• Application_deleteByExtUuidDeletes an application. Arguments: extUuid.

Example: create an application per customer

mutation {
  Application_createFromTemplate(
    templateId: 12, name: "customer-4821", clusterId: 3,
    extUuid: "cust-4821"
  ) { id name domain }
}

Troubleshooting

• The cluster never reaches configured. Check that the cluster can reach your workspace over HTTPS, including through any proxy, and that the install token had not expired.
• An application stays pending. Applications run once they are approved and enabled. Check the approval, then the cluster's capacity.
• The CI call returns 401. Check that the user is project plus the template ID, that the key belongs to that template, and that projectId is in the request body.
• A new version did not deploy. Check that image matches a service name in the template, and that the application follows that version.

Still stuck? Email hello@shipfast.app.