Create Virtual Cluster Environments from CI Pipelines¶

GitHub Actions Instructions¶

Follow this example and our GitHub Actions:

• Example Configuration
• Cluster Action
• Setup Action

Overview of the process¶

This guide will walk you through the process of creating Uffizzi cluster (uCluster) environments using Continuous Integration (CI) pipelines with Uffizzi. uCluster environments provide an isolated and reproducible environment for your applications, allowing you to easily test and deploy your code in a controlled setting. We will leverage the power of Uffizzi to set up and manage these environments directly from your CI pipelines.

Adding the ability to create virtual cluster environments from you GitHub Actions workflow involves the following steps:

1. Create a new Uffizzi Workflow - A file named .github/workflows/uffizzi.yaml in your repository and configure the workflow.

2. Define build jobs - Build and push platform specific artifacts.

3. Deploy Uffizzi Cluster - Create a uCluster with the application built in step 2.

For a more detailed example and additional configurations, refer to the complete example in the UffizziCloud repository.

Create a new Uffizzi Workflow¶

In this section, we'll create a new GitHub workflow within the application repository -- Add a name, then define when it runs -- also provide the following permissions:

name: Uffizzi Cluster Quickstart

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

permissions:
  contents: read
  pull-requests: write
  id-token: write

Define build jobs¶

For each of the application components define the various configurations required to build the application. For example, Replace build-foo and build-bar with your actual build job names and configurations:

jobs:
  build-foo:
    ...
  build-bar:
    ...

Deploy Uffizzi Cluster¶

Create a cluster job within the workflow that utilizes the Uffizzi cluster-action. This job will deploy your application to the uCluster. As seen in the code snippet -- the UffizziCloud/cluster-action@main action is called with the cluster-name: pr-${{ github.event.pull_request.number }} parameter. This creates a new uffizzi cluster (uCluster) with the name pr-{pr number}.

In this workflow, we use Kustomize to customize our Kubernetes manifests before applying them to the Uffizzi Virtual Cluster. Here's how it works:

• We fetch the Docker image tags generated by previous build jobs (e.g., needs.build-vote.outputs.tags).
• We use Kustomize to update the image references in our Kubernetes manifests, ensuring they point to the newly built and pushed images.

uffizzi-cluster:
  name: Deploy to Uffizzi Virtual Cluster
   ...
   ...
  # Create a uCluster with cluster-name as pr-number
  - name: Connect to Virtual Cluster
    uses: UffizziCloud/cluster-action@main
    with:
      cluster-name: pr-${{ github.event.pull_request.number }}

  # Edit manifests and Apply
  - name: Kustomize and Apply Manifests
    id: prev
    run: |
      # Change the image name to those just built and pushed.
      kustomize edit set image my-registry/image_name=${{ needs.build-vote.outputs.tags }}
      kustomize edit set image my-registry/image_name=${{ needs.build-result.outputs.tags }}

      # Apply kustomized manifests to virtual cluster.
      kubectl apply --kustomize . --kubeconfig ./kubeconfig

Alternatively, the helm --set command can be integrated into the workflow to modify image references within a Helm chart values.yaml file:

 # Apply Harbor Helm Chart
 - name: Apply Helm Chart
   id: helm
   run: |
     export vote=$(echo ${{ needs.build-vote.outputs.tags }} 
     export result=$(echo ${{ needs.build-result.outputs.tags }}

     export KUBECONFIG="`pwd`/kubeconfig"
     helm repo add <helm-repo> <helm-repo-url>

     helm upgrade --install my-release \
       --set vote.image.repository=${REPO_portal} \
       --set vote.image.tag=24h \
       --set result.image.repository=${REPO_core} \
       --set result.image.tag=24h \
       <helm-repo>/<helm-chart> --values=values.yaml

GitLab CI Instructions¶

Introduction¶

This guide outlines how to integrate Uffizzi virtual cluster environments into your GitLab CI/CD pipelines. GitLab CI allows you to automate tasks triggered by events like pull requests, ensuring a smooth and consistent development and deployment process. Check out the Example Configuration for GitLab CI integration details.

Pipeline Stages¶

The GitLab pipeline consists of five main stages, each serving a specific purpose:

...
services:
 ...

stages:
  - build
  - uffizzi_cluster_deploy
  - kustomize_apply
  - add_comment
  - uffizzi_cluster_delete
...

Build¶

The build stage handles the building and pushing of application images to a temporary Uffizzi registry. This stage ensures that your application components are packaged and ready for deployment.

Uffizzi Cluster Deploy¶

The uffizzi_cluster_deploy stage refers to the deploy_cluster_environment job, which is defined in the included cluster.gitlab-ci.yml file. This job is responsible for deploying a Uffizzi cluster environment for the merge request.

This job performs the following tasks:

• Checks if the environment already exists and updates it if necessary.
• Logs in to Uffizzi using identity tokens.
• Creates or updates the Uffizzi cluster environment for the merge request.
• Configures the Kubernetes cluster access.

include:
  - "https://gitlab.com/uffizzicloud/cluster-action/raw/main/cluster.gitlab-ci.yml"

variables:
 ...

Kustomize Apply¶

The kustomize_apply stage refers to the kustomize_template job within the cluster.gitlab-ci.yml file. This job applies Kubernetes customizations using kustomize and ensures that your application is configured correctly for the Uffizzi environment.

This job performs the following tasks:

• Downloads kubectl and kustomize.
• Repeats some of the steps from the uffizzi_cluster_deploy stage for authentication.
• Applies K8s manifests using kustomize.

.kustomize_template: &kustomize_template
  stage: kustomize_apply
  rules:
    - if: $CI_MERGE_REQUEST_ID
      ...

Add Comment¶

The add_comment stage adds important Uffizzi cluster command details as comments to the merge request. This helps developers access and manage the Uffizzi cluster environment effectively.

Uffizzi Cluster Delete¶

The uffizzi_cluster_delete stage deletes the Uffizzi cluster once the merge request is closed. This ensures that resources are cleaned up when they are no longer needed.

Now you're ready to harness the power of Uffizzi Virtual Cluster Environments within your CI/CD pipelines. If you have any questions or need assistance, feel free to reach out to our support team. Happy coding!