Uffizzi Ephemeral Cluster Environments (Virtualized Kubernetes)

Deploy Uffizzi Ephemeral Cluster Environments (uClusters) for every pull request.

Similar to the concept of virtual machines, Uffizzi ephemeral clusters are virtualized instances of Kubernetes clusters running on top of a host cluster. Uffizzi virtual clusters provide all the same functionality of real Kubernetes clusters, while being more convenient and efficient.

Uffizzi integrates as a step in your GitHub Actions pipeline to manage on-demand, ephemeral test environments for every feature branch/pull request. Ephemeral Cluster Environments are deployed on Uffizzi Cloud (SaaS) or your own installation of Uffizzi Enterprise or open-source Uffizzi.

Using the Action (recommended usage)

If you wish to use this action by itself outside of the reusable workflow described above, you can. The action can create or delete uClusters.

Inputs

server

(Optional) https://app.uffizzi.com/ or the URL of your Uffizzi installation.

cluster-name

(Optional) The name of the cluster spun up by the uffizzi cluster create command.

image

(Optional) Uffizzi CLI Image. Default value is "uffizzi/cli:v2".

kubeconfig

(Optional) Path to kubeconfig file.

action

(Optional) Specify whether to create or delete a cluster. Default value is "create".

Reusable Workflow (alternate usage)

We've published a Reusable Workflow for your GitHub Actions. This can handle creating, updating, and deleting Uffizzi Ephemeral Cluster Environments. It will also publish instructions for connecting to your cluster in a comment to your pull requests.

Example usage

- name: Create cluster
  id: create-cluster
  if: ${{ env.UFFIZZI_ACTION == 'create' }} || ${{ env.UFFIZZI_ACTION == 'update' }}
  uses: UffizziCloud/cluster-action@reusable
  with:
    action: create
    cluster-name: pr-$PR_NUMBER
    k8s-manifest-file: ${{ inputs.k8s-manifest-cache-path }}
    server: ${{ inputs.server }}

Workflow Calling Example

In this example, three images (vote, result, and worker) are built and published to a temporary image registry exclusively for pull request events. The details of the built image is then updated within the Kubernetes manifest using Kustomize. By following this process, the Uffizzi Cluster is created, and the Kubernetes manifests from the repository are applied.

For more information see Uffizzi Quickstart for K8s.

name: Uffizzi Cluster Example

on:
  pull_request:
    types: [opened,reopened,synchronize,closed]

permissions:
  id-token: write

jobs:      
  build-vote:
    name: Build and Push `vote`
    runs-on: ubuntu-latest
    if: ${{ github.event_name != 'pull_request' || github.event.action != 'closed' }}
    outputs:
      tags: ${{ steps.meta.outputs.tags }}
    steps:
      - name: Checkout git repo
        uses: actions/checkout@v3
      - name: Generate UUID image name
        id: uuid
        run: echo "UUID_VOTE=$(uuidgen)" >> $GITHUB_ENV
      - name: Docker metadata
        id: meta
        uses: docker/metadata-action@v4
        with:
          # An anonymous, emphemeral registry built on ttl.sh
          images: registry.uffizzi.com/${{ env.UUID_VOTE }}
          tags: type=raw,value=24h
      - name: Build and Push Image to Uffizzi Ephemeral Registry
        uses: docker/build-push-action@v3
        with:
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          context: ./vote

  build-worker:
    name: Build and Push `worker`
    runs-on: ubuntu-latest
    if: ${{ github.event_name != 'pull_request' || github.event.action != 'closed' }}
    outputs:
      tags: ${{ steps.meta.outputs.tags }}
    steps:
      - name: Checkout git repo
        uses: actions/checkout@v3
      - name: Generate UUID image name
        id: uuid
        run: echo "UUID_WORKER=$(uuidgen)" >> $GITHUB_ENV
      - name: Docker metadata
        id: meta
        uses: docker/metadata-action@v4
        with:
          # An anonymous, emphemeral registry built on ttl.sh
          images: registry.uffizzi.com/${{ env.UUID_WORKER }}
          tags: type=raw,value=24h
      - name: Build and Push Image to Uffizzi Ephemeral Registry
        uses: docker/build-push-action@v3
        with:
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          context: ./worker

  build-result:
    name: Build and Push `result`
    runs-on: ubuntu-latest
    if: ${{ github.event_name != 'pull_request' || github.event.action != 'closed' }}
    outputs:
      tags: ${{ steps.meta.outputs.tags }}
    steps:
      - name: Checkout git repo
        uses: actions/checkout@v3
      - name: Generate UUID image name
        id: uuid
        run: echo "UUID_RESULT=$(uuidgen)" >> $GITHUB_ENV
      - name: Docker metadata
        id: meta
        uses: docker/metadata-action@v4
        with:
          # An anonymous, emphemeral registry built on ttl.sh
          images: registry.uffizzi.com/${{ env.UUID_RESULT }}
          tags: type=raw,value=24h
      - name: Build and Push Image to Uffizzi Ephemeral Registry
        uses: docker/build-push-action@v3
        with:
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          context: ./result

  cluster-setup:
    name: Setup ucluster
    uses: UffizziCloud/cluster-action/.github/workflows/reusable.yaml@main
    permissions:
      contents: read
      pull-requests: write
      id-token: write

  apply-manifests: 
    runs-on: ubuntu-latest
    needs:
      - build-vote
      - build-worker
      - build-result
      - cluster-setup
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Download artifact
        uses: actions/download-artifact@v3
        with:
          name: my-artifact

      - name: Kustomize and apply
        run: |

          kustomize edit set image vote-image=${{ needs.build-vote.outputs.tags }}
          kustomize edit set image result-image=${{ needs.build-result.outputs.tags }}
          kustomize edit set image worker-image=${{ needs.build-worker.outputs.tags }}

          kustomize build . | kubectl apply --kubeconfig kubeconfig -f -

          if kubectl get ingress vote-${{ github.event.number }} --kubeconfig kubeconfig >/dev/null 2>&1; then
            echo "Ingress vote-${{ github.event.number }} already exists"

          else
            kubectl create ingress vote-${{ github.event.number }} \
              --class=nginx \
              --rule="pr-${{ github.event.number }}-vote.app.qa-gke.uffizzi.com/*=vote:5000" \
              --kubeconfig kubeconfig
          fi

          if kubectl get ingress result-${{ github.event.number }} --kubeconfig kubeconfig >/dev/null 2>&1; then
            echo "Ingress result-${{ github.event.number }} already exists"

          else     
            kubectl create ingress result-${{ github.event.number }} \
              --class=nginx \
              --rule="pr-${{ github.event.number }}-result.app.qa-gke.uffizzi.com/*=result:5001" \
              --kubeconfig kubeconfig
          fi

          echo "Access the vote endpoint at \`pr-${{ github.event.number }}-vote.app.qa-gke.uffizzi.com\`." | tee --append $GITHUB_STEP_SUMMARY
          echo "Access the result endpoint at \`pr-${{ github.event.number }}-result.app.qa-gke.uffizzi.com\`." | tee --append $GITHUB_STEP_SUMMARY

Reusable Workflow Inputs

username

(Optional) Uffizzi username for login, usually an email address.

server

(Optional) Uffizzi server URL. Default value is "https://app.uffizzi.com".

project

(Optional) Uffizzi project name. Default value is "default".

pr-number

(Optional) GitHub Pull Request Number

git-ref

(Optional) Branch or other git reference to checkout

healthcheck-url-path

(Optional) URL Path to the Uffizzi Cluster URL where healthcheck would be performed. The URL Path has to start with a '/'.

description

(Optional) Text string added to comment on pull request issue. Default value is "What is Uffizzi? Learn more".

environment

(Optional) Custom environment for the deployed cluster. Default value is "uffizzi".

image

(Optional) Uffizzi CLI Image. Default value is "uffizzi/cli:v2".