GitLab CI Virtual Cluster Example

Follow the example guide below to see what how the Uffizzi virtual cluster integration with GitLab CI works end-to-end.

Get Starteds

Fork the quickstart repo

Start by forking the quickstart-k8s (opens in a new tab) repository on GitLab.

From the project home page, select Fork, then choose a namespace and project slug. Select Fork project.

Enable CI/CD

Ensure GitLab CI/CD is enabled for your project. If you don't see the Build > Pipelines option in left sidebar, following these steps (opens in a new tab) to enable it.

Open a Merge Request

Open a merge request (MR) for try-uffizzi branch against master in your fork.

⚠️

Be sure that you’re opening the MR on the branches of your fork (i.e. your-account/master ← your-account/try-uffizzi).

If you try to open a MR for uffizzi/quickstart/~/tree/master ← your-account/~/tree/try-uffizzi, the pipeline will not run in this example.

This will kick off a GitLab pipeline and the ephemeral environment URL will be dumped to stdout of the pipeline job.

What to expect

The MR will trigger a pipeline defined in .gitlab-ci.yml (opens in a new tab) that creates a Uffizzi ephemeral environment and deploys the Hello World application defined by this repo. The ephemeral environment URL (See Uffizzi Ingress will be echoed to stdout of the deploy_environment Job. Look for the following line in the Job logs:

This virtual cluster is configured with a Uffizzi Ingress, which makes the web service available at a predictable URL, consisting of https://app.uffizzi.com/ appended with the GitHub pull request domain. For example:
https://app.uffizzi.com/github.com/{account}/{repo}/pull/{pull-request-number}.

You can make requests to specific endpoints by appending a route to the end of the URL. For example:
https://app.uffizzi.com/github.com/boxyhq/jackson/pull/661/api/health

To learn how to enable predicable URLs for your ephemeral environments, see the Uffizzi Ingress documentation.

How it works

Ephemeral environments are configured with a kustomization.yaml (opens in a new tab) that describes the service, ingress, and deployment' components and a [GitLab CI pipeline](https://gitlab.com/uffizzicloud/quickstart/-/blob/master/.gitlab-ci.yml) that includes a series of jobs triggered by a merge_request_event`:

Build and Push the Image
Create a virtual cluster using the Uffizzi CLI in a GitLab CI pipeline runner
Apply a kustomization to deploy the application on the virtual cluster
Delete the virtual cluster when the PR is closed or merged

Connecting to the Cluster

To run kubectl commands on this cluster, first update your kubeconfig by running:

uffizzi cluster update-kubeconfig [CLUSTER_NAME]

💡

Tip: We recommend using the merge request number for cluster names to make it easy to connect to your clusters, e.g.: uffizzi cluster update-kubeconfig mr-281

To find the ingress of this deployment, run:

kubectl get ingress web --kubeconfig ~/.kube/config -o json | jq '.spec.rules[0].host' | tr -d '"'

Next Steps

Now that you've seen the process from start to finish, add Uffizzi to your own project on GitLab.

OIDC Example